1########################
2Documentation generation
3########################
4
5Two documents are available for generation:
6
7- Reference Manual (HTML, PDF)
8- User Guide (HTML, PDF)
9
10The documentation build is independent from building the binary artifacts.
11
12.. _build-environment-setup:
13
14******************************
15Tools and building environment
16******************************
17
18These tools are used to generate TF-M documentation:
19
20    - Doxygen v1.8.0 or later
21    - Graphviz dot v2.38.0 or later
22    - PlantUML v1.2018.11 or later
23    - Java runtime environment v1.8 or later (for running PlantUML)
24    - (Optional) `uv <https://docs.astral.sh/uv/getting-started/installation/#standalone-installer>`
25
26Additionally, for PDFs format:
27
28    - LaTeX
29    - PdfLaTeX
30
31There are two ways of building TF-M reference manual:
32
33    1. As a custom target of TF-M CMake build system
34    2. Directly, using the command line tools
35
36
37To prepare your building environment execute the following steps:
38
39.. tabs::
40
41    .. group-tab:: Linux
42
43        Install the required tools:
44
45        .. code-block:: bash
46
47            sudo apt-get install -y doxygen graphviz default-jre
48            mkdir ~/plantuml
49            curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
50
51            # For PDF generation
52            sudo apt-get install -y doxygen-latex librsvg2-bin
53
54            # Setup python venv for the project
55            python3 -m venv .venv
56
57            # NOTE: If your system python install version is <3.10 you can use `uv <https://docs.astral.sh/uv/getting-started/installation/#standalone-installer>` to setup your .venv
58            uv venv --python 3.12
59
60            source .venv/bin/activate
61            pip install ".[docs]"
62
63
64            # NOTE: If you've used `uv` to setup your `.venv`, prepend the `pip` commands with `uv`
65            uv pip install ".[docs]"
66
67        Set the environment variables:
68
69        .. code-block:: bash
70
71            export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
72
73    .. group-tab:: Windows
74
75        Download and install the following tools:
76
77            - `Doxygen 1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
78            - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
79            - The Java runtime is part of the Arm DS installation or can be
80               downloaded from `here <https://www.java.com/en/download/>`__
81            - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
82            -  `MikTeX <https://miktex.org/download>`__ - for PDF generation only
83
84        Set the environment variables, assuming that:
85
86            - doxygen, dot, and MikTeX binaries are available on the PATH.
87            - Java JVM is used from Arm DS installation.
88
89        .. code-block:: bash
90
91            set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
92            set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
93
94            # Install the required Python modules
95
96            # Setup python venv for the project
97            python3 -m venv .venv
98
99            # NOTE: If your system python install version is <3.10 you can use `uv <https://docs.astral.sh/uv/getting-started/installation/#standalone-installer>` to setup your .venv
100            uv venv --python 3.12
101
102            source .venv/bin/activate
103            pip install ".[docs]"
104            # If uv is installed
105            uv pip install ".[docs]"
106
107            # NOTE: If you've used `uv` to setup your `.venv`, prepend the `pip` commands with `uv`
108            uv pip sync pylock.toml
109
110***************************
111Build TF-M Reference Manual
112***************************
113
114The Reference Manual will be generated in the ``build_docs/reference_manual``.
115
116.. Note::
117   Please make sure to follow :ref:`Tools and building environment <build-environment-setup>`
118   before proceeding
119
120.. tabs::
121
122    .. group-tab:: Linux
123
124        .. code-block:: bash
125
126            cd <TF-M base folder>
127            source .venv/bin/activate
128            cmake -S docs -B build_docs
129            cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf
130
131    .. group-tab:: Windows
132
133        .. code-block:: bash
134
135            cd <TF-M base folder>
136            source .venv/bin/activate
137            pip install ".[docs]"
138            # If uv is installed
139            uv pip install ".[docs]"
140            cmake -S docs -B build_docs -G"Unix Makefiles"
141            cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf
142
143*********************
144Build TF-M User Guide
145*********************
146
147The User Manual will be available under the directory ``build_docs/user_guide``.
148
149.. tabs::
150
151    .. group-tab:: Linux
152
153        .. code-block:: bash
154
155            cd <TF-M base folder>
156            source .venv/bin/activate
157            cmake -S docs -B build_docs
158            cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf
159
160    .. group-tab:: Windows
161
162        .. code-block:: bash
163
164            cd <TF-M base folder>
165            source .venv/bin/activate
166            cmake -S docs -B build_docs -G"Unix Makefiles"
167            cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf
168
169
170***************************************
171Direct build using a command line tools
172***************************************
173
174The direct build will build both user_guide and reference_manual.
175
176
177.. tabs::
178
179    .. group-tab:: Linux
180
181        .. code-block:: bash
182
183            # Build the documentation from build_docs directory
184            cd <TF-M base folder>
185            source .venv/bin/activate
186            mkdir build_docs
187            cp docs/conf.py build_docs/conf.py
188            cd build_docs
189            sphinx-build ./ user_guide
190
191    .. group-tab:: Windows
192
193        .. code-block:: bash
194
195            # Command line tools is yet not available for Windows
196
197************
198Dependencies
199************
200
201.. uml::
202
203   @startuml
204    skinparam state {
205      BackgroundColor #92AEE0
206      FontColor black
207      FontSize 16
208      AttributeFontColor black
209      AttributeFontSize 16
210      BackgroundColor<<pdf>> #A293E2
211      BackgroundColor<<doc>> #90DED6
212    }
213    state u_guide as "User Guide" <<doc>>
214    state refman as "Reference Manual" <<doc>>
215    state rtd_theme as "sphinx-rtd-theme" <<doc>>
216    state tabs as "sphinx-tabs" <<doc>>
217    state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
218    state sphnix_svg as "sphinxcontrib-svg2pdfconverter" <<doc>>
219    state JRE as "JRE" <<doc>> : Java Runtime Environment
220    state gwiz as "Graphwiz dot" <<doc>>
221    state Sphinx as "Sphinx" <<doc>>
222    state python as "Python v3" <<doc>>
223    state m2r as "m2r2" <<doc>>
224    state PlantUML as "PlantUML" <<doc>>
225    state LaTex as "LaTex" <<pdf>>
226    state PdfLaTex as "PdfLaTex" <<pdf>>
227    state Doxygen as "Doxygen" <<doc>>
228    state librsvg as "librsvg2-bin" <<doc>>
229
230    [*] --> u_guide
231    u_guide --> Sphinx
232    Sphinx --> m2r
233    Sphinx --> rtd_theme
234    Sphinx --> tabs
235    Sphinx --> sphnix_puml
236    Sphinx --> sphnix_svg
237    m2r --> python
238    rtd_theme --> python
239    tabs --> python
240    sphnix_puml --> python
241    sphnix_svg --> python
242    sphnix_svg --> librsvg
243    Sphinx --> PlantUML
244    PlantUML --> JRE
245    PlantUML --> gwiz
246    Sphinx --> LaTex
247    LaTex --> PdfLaTex
248
249    [*] --> refman
250    refman --> Doxygen
251    Doxygen --> PlantUML
252    Doxygen --> LaTex
253    state Legend {
254      state x as "For PDF generation only" <<pdf>>
255    }
256
257   @enduml
258
259
260.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
261.. _Doxygen: https://www.doxygen.nl
262
263--------------
264
265*Copyright (c) 2017-2024, Arm Limited. All rights reserved.*
266