docs: Clarify documentation for binaries and docs builds
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I0a412426c40717e086c9bc4330cbb27a4cc810ad
diff --git a/docs/getting_started/tfm_getting_started.rst b/docs/getting_started/tfm_getting_started.rst
index 4e32ec3..5ea61b1 100644
--- a/docs/getting_started/tfm_getting_started.rst
+++ b/docs/getting_started/tfm_getting_started.rst
@@ -338,38 +338,15 @@
To build the TF-M firmware the following tools are needed:
-.. csv-table:: Tool dependencies
- :header: "Name", "Version", "Component"
+ - C compiler of supported toolchains
+ - CMake version 3.15 or later
+ - Git
+ - gmake, aka GNU Make
+ - Python v3.x
+ - a set of python modules listed in ``tools/requiremtns.txt``
- "C compiler",,"Firmware"
- "CMake",,
- "GNU Make",,
- "tf-m-tests",CMake handles it,
- "mbed-crypto",CMake handles it,
- "MCUboot",CMake handles it,
- "Python",3.x,"Firmware, User Guide"
- "yaml",,"Firmware"
- "pyasn1",,"Firmware"
- "jinja2",,"Firmware"
- "cryptography",,"Firmware"
- "cbor",,"Firmware"
- "click",,"Firmware"
- "imgtool",,"Firmware"
- "Doxygen",">1.8","Reference manual"
- "Sphinx","=2.0.1","User Guide"
- "sphinxcontrib-plantuml",,"User Guide"
- "sphinxcontrib-svg2pdfconverter",,"User Guide"
- "sphinx-rtd-theme",,"User Guide"
- "sphinx-tabs",,"User Guide"
- "Git",,
- "PlantUML",">v1.2018.11","Reference Manual, User Guide"
- "Graphviz dot",">v2.38.0","Reference manual"
- "Java runtime environment (JRE)",">1.8","Reference Manual, User Guide"
- "LaTex",,"pdf version of Reference Manual and User Guide"
- "PdfLaTex",,"pdf version of Reference Manual and User Guide"
- "librsvg2-bin",, "User Guide"
-
-Dependency chain:
+Dependency chain
+----------------
.. uml::
@@ -380,32 +357,15 @@
FontSize 16
AttributeFontColor black
AttributeFontSize 16
- BackgroundColor<<pdf>> #A293E2
- BackgroundColor<<doc>> #90DED6
}
state fw as "Firmware" : TF-M binary
state c_comp as "C Compiler" : C99
- state gmake as "GNU make"
- state u_guide as "User Guide" <<doc>>
- state refman as "Reference Manual" <<doc>>
- state rtd_theme as "sphinx-rtd-theme" <<doc>>
- state tabs as "sphinx-tabs" <<doc>>
- state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
- state sphnix_svg as "sphinxcontrib-svg2pdfconverter" <<doc>>
- state JRE as "JRE" <<doc>> : Java Runtime Environment
- state gwiz as "Graphwiz dot" <<doc>>
- state Sphinx as "Sphinx" <<doc>>
- state m2r as "m2r" <<doc>>
- state PlantUML as "PlantUML" <<doc>>
- state LaTex as "LaTex" <<pdf>>
- state PdfLaTex as "PdfLaTex" <<<<pdf>>>>
- state Doxygen as "Doxygen" <<doc>>
- state librsvg as "librsvg2-bin" <<doc>>
+ state python as "Python" : v3.x
- [*] --> fw
fw --> c_comp
fw --> CMake
CMake --> gmake
+ CMake --> Ninja
fw --> cryptography
fw --> pyasn1
fw --> yaml
@@ -413,43 +373,16 @@
fw --> cbor
fw --> click
fw --> imgtool
- cryptography --> Python3
- pyasn1 --> Python3
- yaml --> Python3
- jinja2 --> Python3
- cbor --> Python3
- click --> Python3
- imgtool --> Python3
-
- [*] --> u_guide
- u_guide --> Sphinx
- Sphinx --> m2r
- Sphinx --> rtd_theme
- Sphinx --> tabs
- Sphinx --> sphnix_puml
- Sphinx --> sphnix_svg
- m2r --> Python3
- rtd_theme --> Python3
- tabs --> Python3
- sphnix_puml --> Python3
- sphnix_svg --> Python3
- sphnix_svg --> librsvg
- Sphinx --> PlantUML
- PlantUML --> JRE
- PlantUML --> gwiz
- Sphinx --> LaTex
- LaTex --> PdfLaTex
-
- [*] --> refman
- refman --> Doxygen
- Doxygen --> PlantUML
- Doxygen --> LaTex
- state Legend {
- state x as "For PDF generation only" <<pdf>>
- state y as "For document generation only" <<doc>>
- state z as "Mandatory"
- }
-
+ c_comp --> GCC
+ c_comp --> CLANG
+ c_comp --> IAR
+ cryptography --> python
+ pyasn1 --> python
+ yaml --> python
+ jinja2 --> python
+ cbor --> python
+ click --> python
+ imgtool --> python
@enduml
##########
diff --git a/docs/technical_references/instructions/documentation_generation.rst b/docs/technical_references/instructions/documentation_generation.rst
index b8bd9ca..219418c 100644
--- a/docs/technical_references/instructions/documentation_generation.rst
+++ b/docs/technical_references/instructions/documentation_generation.rst
@@ -2,33 +2,42 @@
Documentation generation
########################
-The build system is prepared to support generation of two documents:
+Two documents are available for generation:
-- Reference Manual. Doxygen based.
-- User Guide. Sphinx based.
+- Reference Manual (HTML, PDF)
+- User Guide (HTML, PDF)
-Both documents can be generated in HTML and PDF format and independently from
-building the project binary artifacts.
+The documentation build is independent from building the binary artifacts.
-***************************
-Build TF-M Reference Manual
-***************************
+******************************
+Tools and building environment
+******************************
-The following tools are needed:
+These tools are used to generate TF-M documentation:
- Doxygen v1.8.0 or later
- Graphviz dot v2.38.0 or later
- PlantUML v1.2018.11 or later
- - Java runtime environment 1.8 or later (for running PlantUML)
- - LaTeX - for PDF generation only
- - PdfLaTeX - for PDF generation only
+ - Java runtime environment v1.8 or later (for running PlantUML)
+ - Sphinx and other python modules, listed in ``tools/requirements_docs.txt``
+
+Additionally, for PDFs format:
+
+ - LaTeX
+ - PdfLaTeX
+
+There are two ways of building TF-M reference manual:
+
+ 1. As a custom target of TF-M CMake build system
+ 2. Directly, using the command line tools
+
+
+To prepare your building environment execute the following steps:
.. tabs::
.. group-tab:: Linux
- 1. Set-up the needed tools and environment:
-
.. code-block:: bash
sudo apt-get install -y doxygen graphviz default-jre
@@ -39,75 +48,54 @@
# For PDF generation
sudo apt-get install -y doxygen-latex
- # Additional Python dependencies for documentation
+ # Install the required Python modules
pip3 install --upgrade pip
cd trusted-firmware-m
pip3 install -r tools/requirements_docs.txt
- 2. Currently, there are two ways of building TF-M reference manual:
-
- - Using the CMake build system as custom targets
-
- .. code-block:: bash
-
- cd <TF-M base folder>
- cmake -S docs -B build_docs
- cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf
-
- The documentation files will be available under the directory ``cmake_doc/docs/reference_manual``.
-
- - Manually using the appropriate tools (`sphinx-build`_/ `Doxygen`_)
-
- .. code-block:: bash
-
- # Build the documentation from build_docs directory
- cd <TF-M base folder>
- mkdir build_docs
- cp docs/conf.py build_docs/conf.py
- cd build_docs
- sphinx-build ./ user_guide
-
- # Build the documentation from a custom location
- # setting the build_docs as input
-
- # Note that using this method will still generate the reference manual
- # to the <TF-M base folder>/build_docs/reference_manual
- cd <TF-M base folder>/<OTHER_DIR>/<OTHER_DIR2>
- sphinx-build <TF-M base folder>/build_docs/ <DESIRED_OUTPUT_DIR>
-
- .. Note::
-
- Invoking Sphinx-build will build both user_guide and
- reference_manual targets.
-
.. group-tab:: Windows
- 1. Download and install the following tools:
+ Download and install the following tools:
- - `Doxygen 1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
- - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
- - The Java runtime is part of the Arm DS installation or can be
- downloaded from `here <https://www.java.com/en/download/>`__
- - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
- - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
+ - `Doxygen 1.8.8 <https://sourceforge.net/projects/doxygen/files/snapshots/doxygen-1.8-svn/windows/doxygenw20140924_1_8_8.zip/download>`__
+ - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the Arm DS installation or can be
+ downloaded from `here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+ - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
- 2. Set the environment variables, assuming that:
+ Set the environment variables, assuming that:
- - doxygen, dot, and MikTeX binaries are available on the PATH.
- - Java JVM is used from Arm DS installation.
+ - doxygen, dot, and MikTeX binaries are available on the PATH.
+ - Java JVM is used from Arm DS installation.
.. code-block:: bash
- # Additional Python dependencies for documentation
- pip3 install --upgrade pip
- cd trusted-firmware-m
- pip3 install -r tools\requirements_docs.txt
-
set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
- 3. Using the CMake build system as custom targets to build TF-M
- reference manual:
+ # Install the required Python modules
+ pip3 install --upgrade pip
+ cd trusted-firmware-m
+ pip3 install -r tools\requirements_docs.txt
+
+***************************
+Build TF-M Reference Manual
+***************************
+
+The Reference Manual will be generated in the ``build_docs/docs/reference_manual``.
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ .. code-block:: bash
+
+ cd <TF-M base folder>
+ cmake -S docs -B build_docs
+ cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf
+
+ .. group-tab:: Windows
.. code-block:: bash
@@ -115,125 +103,119 @@
cmake -S docs -B build_docs -G"Unix Makefiles"
cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf
- The documentation files will be available under the directory ``build_docs\docs\reference_manual``.
-
*********************
Build TF-M User Guide
*********************
-The following tools are needed:
-
- - Python3 and the following modules:
- - Sphinx v2.0.1
- - m2r v0.2.0
- - sphinxcontrib-plantuml
- - sphinxcontrib-svg2pdfconverter
- - sphinx-rtd-theme
- - docutils v0.16
- - Graphviz dot v2.38.0 or later
- - PlantUML v1.2018.11 or later
- - Java runtime environment 1.8 or later (for running PlantUML)
- - LaTeX - for PDF generation only
- - PdfLaTeX - for PDF generation only
- - librsvg2-bin - a SVG pictures renderer library to support
- sphinxcontrib-svg2pdfconverter
+The User Manual will be available under the directory ``build_docs/docs/user_guide``.
.. tabs::
.. group-tab:: Linux
- 1. Set-up the tools and environment:
-
.. code-block:: bash
- sudo apt-get install -y python3 graphviz default-jre librsvg2-bin
- pip install -r tools/requirements.txt
- mkdir ~/plantuml
- curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
-
- # For PDF generation
- sudo apt-get install -y doxygen-latex
- export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
-
- 2. Currently, there are two ways of building TF-M user guide:
-
- - Using the CMake build system as custom targets
-
- .. code-block:: bash
-
- cd <TF-M base folder>
- cmake -S docs -B build_docs
- cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf
-
- The documentation files will be available under the directory ``build_docs/docs/user_guide``.
-
- - Manually using the appropriate tools (`sphinx-build`_/ `Doxygen`_)
-
- .. code-block:: bash
-
- # Build the documentation from build_docs directory
- cd <TF-M base folder>
- mkdir build_docs
- cp docs/conf.py build_docs/conf.py
- cd build_docs
- sphinx-build ./ user_guide
-
- # Build the documentation from a custom location
- # setting the build_docs as input
-
- # Note that using this method will still generate the reference manual
- # to the <TF-M base folder>/build_docs/reference_manual
- cd <TF-M base folder>/<OTHER_DIR>/<OTHER_DIR2>
- sphinx-build <TF-M base folder>/build_docs/ <DESIRED_OUTPUT_DIR>
-
- .. Note::
-
- Invoking Sphinx-build will build both user_guide and
- reference_manual targets.
+ cd <TF-M base folder>
+ cmake -S docs -B build_docs
+ cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf
.. group-tab:: Windows
- 1. Download and install the following tools:
-
- - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
- - The Java runtime is part of the Arm DS installation or can be `downloaded from here <https://www.java.com/en/download/>`__
- - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
- - `MikTeX <https://miktex.org/download>`__ - for PDF generation only
- - Python3 `(native Windows version) <https://www.python.org/downloads/>`__
- - The necessary Python3 packages are listed in the requirements.txt file.
-
- To install all needed packages just do:
-
- .. code-block:: bash
-
- pip install -r tools\requirements.txt
-
- .. Note::
- When building the documentation the first time, MikTeX might prompt
- for installing missing LaTeX components. Please allow the MikTeX
- package manager to set-up these.
-
- 2. Set the environment variables, assuming that:
-
- - plantuml.jar is available at c:\\plantuml\\plantuml.jar
- - doxygen, dot, and MikTeX binaries are available on the PATH.
- - Java JVM is used from DS5 installation.
-
- .. code-block:: bash
-
- set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
- set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
-
- 3. Using the CMake build system as custom targets to build TF-M user
- guide:
-
.. code-block:: bash
cd <TF-M base folder>
cmake -S docs -B build_docs -G"Unix Makefiles"
cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf
- The documentation files will be available under the directory ``build_docs\docs\user_guide``.
+
+***************************************
+Direct build using a command line tools
+***************************************
+
+The direct build will build both user_guide and reference_manual.
+
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ .. code-block:: bash
+
+ # Build the documentation from build_docs directory
+ cd <TF-M base folder>
+ mkdir build_docs
+ cp docs/conf.py build_docs/conf.py
+ cd build_docs
+ sphinx-build ./ user_guide
+
+ .. group-tab:: Windows
+
+ .. code-block:: bash
+
+ # Command line tools is yet not available for Windows
+
+############
+Dependencies
+############
+
+.. uml::
+
+ @startuml
+ skinparam state {
+ BackgroundColor #92AEE0
+ FontColor black
+ FontSize 16
+ AttributeFontColor black
+ AttributeFontSize 16
+ BackgroundColor<<pdf>> #A293E2
+ BackgroundColor<<doc>> #90DED6
+ }
+ state u_guide as "User Guide" <<doc>>
+ state refman as "Reference Manual" <<doc>>
+ state rtd_theme as "sphinx-rtd-theme" <<doc>>
+ state tabs as "sphinx-tabs" <<doc>>
+ state sphnix_puml as "sphinxcontrib-plantuml" <<doc>>
+ state sphnix_svg as "sphinxcontrib-svg2pdfconverter" <<doc>>
+ state JRE as "JRE" <<doc>> : Java Runtime Environment
+ state gwiz as "Graphwiz dot" <<doc>>
+ state Sphinx as "Sphinx" <<doc>>
+ state python as "Python v3" <<doc>>
+ state m2r as "m2r2" <<doc>>
+ state PlantUML as "PlantUML" <<doc>>
+ state LaTex as "LaTex" <<pdf>>
+ state PdfLaTex as "PdfLaTex" <<pdf>>
+ state Doxygen as "Doxygen" <<doc>>
+ state librsvg as "librsvg2-bin" <<doc>>
+
+ [*] --> u_guide
+ u_guide --> Sphinx
+ Sphinx --> m2r
+ Sphinx --> rtd_theme
+ Sphinx --> tabs
+ Sphinx --> sphnix_puml
+ Sphinx --> sphnix_svg
+ m2r --> python
+ rtd_theme --> python
+ tabs --> python
+ sphnix_puml --> python
+ sphnix_svg --> python
+ sphnix_svg --> librsvg
+ Sphinx --> PlantUML
+ PlantUML --> JRE
+ PlantUML --> gwiz
+ Sphinx --> LaTex
+ LaTex --> PdfLaTex
+
+ [*] --> refman
+ refman --> Doxygen
+ Doxygen --> PlantUML
+ Doxygen --> LaTex
+ state Legend {
+ state x as "For PDF generation only" <<pdf>>
+ }
+
+ @enduml
+
.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
.. _Doxygen: https://www.doxygen.nl
diff --git a/tools/documentation/tfm_cmake_defaults.py b/tools/documentation/tfm_cmake_defaults.py
index 9da42e1..e81d5fb 100644
--- a/tools/documentation/tfm_cmake_defaults.py
+++ b/tools/documentation/tfm_cmake_defaults.py
@@ -105,7 +105,7 @@
tfm_def_doc_root = os.path.join(tfm_def_root_dir, "docs")
tfm_def_copy_doc_root = os.path.join(tfm_def_copy_dir, "docs")
- tfm_def_doxy_root = os.path.join(tfm_def_root_dir, "doxygen")
+ tfm_def_doxy_root = os.path.join(tfm_def_doc_root, "doxygen")
tfm_def_doxy_output_dir = os.path.join(tfm_def_copy_dir,
tfm_def_doxy_output_dir)