From 7cb68807fbd2138bfc71ace3548e4366d15daacf Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Fri, 12 Jul 2019 11:56:58 +0100 Subject: [PATCH] doc: Generate PlantUML diagrams automatically Currently we have some pre-rendered versions of certain diagrams in SVG format. These diagrams have corresponding PlantUML source that can be rendered automatically as part of the documentation build, removing the need for any intermediate files. This patch adds the Sphinx "plantuml" extension, replaces references to the pre-rendered SVG files within the documents, and finally removes the SVG files and helper script. New requirements for building the docs are the "sphinxcontrib-plantuml" Python module (added to the pip requirements.txt file) and the Graphviz package (provides the "dot" binary) which is in the Ubuntu package repositories. Change-Id: I24b52ee40ff79676212ed7cff350294945f1b50d Signed-off-by: Paul Beesley --- docs/components/sdei.rst | 4 ++-- docs/conf.py | 8 ++++++-- docs/requirements.txt | 3 ++- docs/resources/diagrams/plantuml/plantuml_to_svg.sh | 13 ------------- .../diagrams/plantuml/sdei_explicit_dispatch.svg | 1 - docs/resources/diagrams/plantuml/sdei_general.svg | 1 - 6 files changed, 10 insertions(+), 20 deletions(-) delete mode 100644 docs/resources/diagrams/plantuml/plantuml_to_svg.sh delete mode 100644 docs/resources/diagrams/plantuml/sdei_explicit_dispatch.svg delete mode 100644 docs/resources/diagrams/plantuml/sdei_general.svg diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst index 6d0e1563d..2a777b385 100644 --- a/docs/components/sdei.rst +++ b/docs/components/sdei.rst @@ -26,7 +26,7 @@ The following figure depicts a general sequence involving SDEI client executing at EL2 and an event dispatch resulting from the triggering of a bound interrupt. A commentary is provided below: -.. image:: ../resources/diagrams/plantuml/sdei_general.svg +.. uml:: ../resources/diagrams/plantuml/sdei_general.puml As part of initialisation, the SDEI client binds a Non-secure interrupt [1], and the SDEI dispatcher returns a platform dynamic event number [2]. The client then @@ -234,7 +234,7 @@ on success, or ``-1`` on failure. The following figure depicts a scenario involving explicit dispatch of SDEI event. A commentary is provided below: -.. image:: ../resources/diagrams/plantuml/sdei_explicit_dispatch.svg +.. uml:: ../resources/diagrams/plantuml/sdei_explicit_dispatch.puml As part of initialisation, the SDEI client registers a handler for a platform event [1], enables the event [3], and unmasks the current PE [5]. Note that, diff --git a/docs/conf.py b/docs/conf.py index 64f12431b..b267de0e8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,7 +23,7 @@ release = version # We don't need these to be distinct # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autosectionlabel'] +extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.plantuml'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -82,4 +82,8 @@ html_theme_options = { # -- Options for autosectionlabel -------------------------------------------- # Only generate automatic section labels for document titles -autosectionlabel_maxdepth = 1 \ No newline at end of file +autosectionlabel_maxdepth = 1 + +# -- Options for plantuml ---------------------------------------------------- + +plantuml_output_format = 'svg_img' diff --git a/docs/requirements.txt b/docs/requirements.txt index 8f95774b6..358ed0e3c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx>=2.0.0 -sphinx-rtd-theme>=0.4.3 \ No newline at end of file +sphinx-rtd-theme>=0.4.3 +sphinxcontrib-plantuml>=0.15 diff --git a/docs/resources/diagrams/plantuml/plantuml_to_svg.sh b/docs/resources/diagrams/plantuml/plantuml_to_svg.sh deleted file mode 100644 index 0bf8588bb..000000000 --- a/docs/resources/diagrams/plantuml/plantuml_to_svg.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/bin/bash - -# Convert all PlantUML files in this directory to SVG files. The plantuml_jar -# environment variable must be set to the path to PlantUML JAR file. - -if [ -z "$plantuml_jar" ]; then - echo "Usage: plantuml_jar=/path/to/plantuml.jar $0 *.puml" >&2 - exit 1 -fi - -java -jar "$plantuml_jar" -nometadata -tsvg "$@" - -# vim:set noet sts=8 tw=80: diff --git a/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.svg b/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.svg deleted file mode 100644 index e12cae2fa..000000000 --- a/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.svg +++ /dev/null @@ -1 +0,0 @@ -SDEI clientSDEI clientEL3EL3SDEISDEIRAS DriverRAS Driver[1]SDEI_EVENT_REGISTER(ev, handler, ...)[2]success[3]SDEI_EVENT_ENABLE(ev)[4]success[5]SDEI_PE_UNMASK()[6]1<<Business as usual>>[7]CRITICAL EVENTCritical event triage[8]dispatch to handleCritical event handling[9]sdei_dispatch_event(ev)Prepare SDEI dispatch[10]dispatchSDEI handler[11]SDEI_EVENT_COMPLETE()Complete SDEI dispatch[12]return[13]error handling done[14]resumes preempted execution<<Normal execution resumes>> \ No newline at end of file diff --git a/docs/resources/diagrams/plantuml/sdei_general.svg b/docs/resources/diagrams/plantuml/sdei_general.svg deleted file mode 100644 index e17211229..000000000 --- a/docs/resources/diagrams/plantuml/sdei_general.svg +++ /dev/null @@ -1 +0,0 @@ -SDEI clientSDEI clientEL3EL3SDEI interrupt sourceSDEI interrupt source[1]SDEI_INTERRUPT_BIND(irq)[2]event number: ev[3]SDEI_EVENT_REGISTER(ev, handler, ...)[4]success[5]SDEI_EVENT_ENABLE(ev)[6]success[7]SDEI_PE_UNMASK()[8]1<<Business as usual>>[9]SDEI interruptPrepare SDEI dispatch[10]dispatchSDEI handler[11]SDEI_EVENT_COMPLETE()Complete SDEI dispatch[12]EOI[13]resumes preempted execution<<Normal execution resumes>> \ No newline at end of file