1Documentation Build Instructions
2================================
3
4To create a rendered copy of this documentation locally you can use the
5`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
6pages.
7
8If you are building the documentation for the first time then you will need to
9check that you have the required software packages, as described in the
10*Prerequisites* section that follows.
11
12Prerequisites
13-------------
14
15For building a local copy of the |TS| documentation you will need, at minimum:
16
17- GNUMake
18- Python 3 (3.5 or later)
19- PlantUML (1.2024.7 or later)
20
21You must also install the Python modules that are specified in the
22``requirements.txt`` file in the root of the ``docs`` directory. These modules
23can be installed using ``pip3`` (the Python Package Installer). Passing this
24requirements file as an argument to ``pip3`` automatically installs the specific
25module versions required.
26
27Example environment
28-------------------
29
30An example set of installation commands for Linux with the following assumptions:
31    #. OS and version: Ubuntu 22.04 LTS
32    #. `virtualenv` is used to separate the python dependencies
33    #. pip is used for python dependency management
34    #. `bash` is used as the shell.
35
36.. code:: shell
37
38    sudo apt install make python3 python3-pip virtualenv python3-virtualenv plantuml
39    wget https://github.com/plantuml/plantuml/releases/download/v1.2024.7/plantuml-1.2024.7.jar -O $HOME/plantuml.jar
40    virtualenv -p python3 ~/sphinx-venv
41    . ~/sphinx-venv/bin/activate
42    pip3 install -r requirements.txt
43    deactivate
44
45.. note::
46   More advanced usage instructions for *pip* are beyond the scope of this
47   document but you can refer to the `pip homepage`_ for detailed guides.
48
49.. note::
50   For more information on Virtualenv please refer to the `Virtualenv documentation`_
51
52Building rendered documentation
53-------------------------------
54
55From the ``docs`` directory of the project, run the following commands.
56
57.. code:: shell
58
59   . ~/sphinx-venv/bin/activate
60   export PLANTUML_JAR_PATH=$HOME/plantuml.jar
61   make clean
62   make
63   deactivate
64
65Output from the build process will be placed in:
66
67::
68
69   <TS root>/docs/_build
70
71Configuring the documentation build
72-----------------------------------
73
74The plantuml binary used during the documentation build can be controlled using
75the following environment variables:
76
77    - ``PLANTUML``: specifies the location of a wrapper script. This must be
78      executable and shall run plantuml.jar with all arguments passed over to
79      the tool. If set, will override other settings.
80
81    - ``PLANTUML_JAR_PATH``: full path to the plantuml.jar file to use. If set,
82      an internal wrapper will be used to call plantuml.
83    - ``JAVA_HOME``: used only is ``PLANTUML_JAR_PATH`` is set to specify the
84      JVM executable location to be used by the internal wrapper. The JVM
85      binary should be JAVA_HOME/bin/java.
86
87      If ``JAVA_HOME`` is not set, then ``java`` available from the ``PATH``
88      will be used. If the executable can not be found on the ``PATH`` the
89      build will fail.
90
91If no environment variable is set, then the default setting of
92``sphinxcontrib.plantuml`` will be used, which is to run a wrapper called
93``plantuml`` from the ``PATH``.
94
95Please find the configuration process implementation in `docs/conf.py``.
96
97--------------
98
99.. _Sphinx: http://www.sphinx-doc.org/en/master/
100.. _pip homepage: https://pip.pypa.io/en/stable/
101.. _`Virtualenv documentation`: https://virtualenv.pypa.io/en/latest/
102
103*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
104
105SPDX-License-Identifier: BSD-3-Clause
106