Documentation Build Instructions

To create a rendered copy of this documentation locally you can use the Sphinx tool to build and package the plain-text documents into HTML-formatted pages.

If you are building the documentation for the first time then you will need to check that you have the required software packages, as described in the Prerequisites section that follows.

Prerequisites

For building a local copy of the TS documentation you will need, at minimum:

GNUMake
Python 3 (3.5 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 can be installed using pip3 (the Python Package Installer). Passing this requirements file as an argument to pip3 automatically installs the specific module versions required.

Example environment

An example set of installation commands for Linux with the following assumptions:

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.

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
deactivate

Note

More advanced usage instructions for pip are beyond the scope of this document but you can refer to the pip homepage for detailed guides.

Note

For more information on Virtualenv please refer to the Virtualenv documentation

Building rendered documentation

From the docs directory of the project, run the following commands.

. ~/sphinx-venv/bin/activate
export PLANTUML_JAR_PATH=$HOME/plantuml.jar
make clean
make
deactivate

Output from the build process will be placed in:

<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`.

SPDX-License-Identifier: BSD-3-Clause