docs: Update Plantuml version
Update the version required for documentation build from 1.2017.15 to
1.2024.7.
Unfortunately Ubuntu (the reference build environment is based on)
package repository has a very old version and the decision was made to
use the latest release instead even though it needs to be installed
manually.
Update the documentation and .readthedocs.yml to ensure RTD uses the
right version.
Change-Id: Ic6222f8e79efcdc53108062941c470522459fdca
Signed-off-by: Gyorgy Szing <gyorgy.szing@arm.com>
diff --git a/docs/developer/docs-build.rst b/docs/developer/docs-build.rst
index 9f36e64..3a11281 100644
--- a/docs/developer/docs-build.rst
+++ b/docs/developer/docs-build.rst
@@ -16,7 +16,7 @@
- GNUMake
- Python 3 (3.5 or later)
-- PlantUML (1.2017.15 or later)
+- PlantUML (1.2024.7 or later)
You must also install the Python modules that are specified in the
``requirements.txt`` file in the root of the ``docs`` directory. These modules
@@ -28,7 +28,7 @@
-------------------
An example set of installation commands for Linux with the following assumptions:
- #. OS and version: Ubuntu 18.04 LTS
+ #. OS and version: Ubuntu 22.04 LTS
#. `virtualenv` is used to separate the python dependencies
#. pip is used for python dependency management
#. `bash` is used as the shell.
@@ -36,6 +36,7 @@
.. code:: shell
sudo apt install make python3 python3-pip virtualenv python3-virtualenv plantuml
+ wget https://github.com/plantuml/plantuml/releases/download/v1.2024.7/plantuml-1.2024.7.jar -O $HOME/plantuml.jar
virtualenv -p python3 ~/sphinx-venv
. ~/sphinx-venv/bin/activate
pip3 install -r requirements.txt
@@ -56,6 +57,7 @@
.. code:: shell
. ~/sphinx-venv/bin/activate
+ export PLANTUML_JAR_PATH=$HOME/plantuml.jar
make clean
make
deactivate
@@ -64,7 +66,33 @@
::
- <tf-a CMF root>/docs/_build/html/
+ <TS root>/docs/_build
+
+Configuring the documentation build
+-----------------------------------
+
+The plantuml binary used during the documentation build can be controlled using
+the following environment variables:
+
+ - ``PLANTUML``: specifies the location of a wrapper script. This must be
+ executable and shall run plantuml.jar with all arguments passed over to
+ the tool. If set, will override other settings.
+
+ - ``PLANTUML_JAR_PATH``: full path to the plantuml.jar file to use. If set,
+ an internal wrapper will be used to call plantuml.
+ - ``JAVA_HOME``: used only is ``PLANTUML_JAR_PATH`` is set to specify the
+ JVM executable location to be used by the internal wrapper. The JVM
+ binary should be JAVA_HOME/bin/java.
+
+ If ``JAVA_HOME`` is not set, then ``java`` available from the ``PATH``
+ will be used. If the executable can not be found on the ``PATH`` the
+ build will fail.
+
+If no environment variable is set, then the default setting of
+``sphinxcontrib.plantuml`` will be used, which is to run a wrapper called
+``plantuml`` from the ``PATH``.
+
+Please find the configuration process implementation in `docs/conf.py``.
--------------