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