docs/technical_references/instructions/documentation_generation.rst - sandbox/pfalcon/trusted-firmware-m - TrustedFirmware Git Browser

 ########################
 Documentation generation
 ########################

 The build system is prepared to support generation of two documents:

 - Reference Manual. Doxygen based.
 - User Guide. Sphinx based.

 Both documents can be generated in HTML and PDF format and independently from
 building the project binary artifacts.

 ***************************
 Build TF-M Reference Manual
 ***************************

 The following tools are needed:

     - 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

 .. tabs::

     .. group-tab:: Linux

         1. Set-up the needed tools and environment:

         .. code-block:: bash

             sudo apt-get install -y doxygen graphviz default-jre
             mkdir ~/plantuml
             curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
             export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar

             # For PDF generation
             sudo apt-get install -y doxygen-latex

             # Additional Python dependencies for documentation
             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:

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

         - 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:

         .. code-block:: bash

             cd <TF-M base folder>
             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

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

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

 .. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
 .. _Doxygen: https://www.doxygen.nl

 --------------

 *Copyright (c) 2017-2021, Arm Limited. All rights reserved.*
	########################
	Documentation generation
	########################

	The build system is prepared to support generation of two documents:

	- Reference Manual. Doxygen based.
	- User Guide. Sphinx based.

	Both documents can be generated in HTML and PDF format and independently from
	building the project binary artifacts.

	***************************
	Build TF-M Reference Manual
	***************************

	The following tools are needed:

	- 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

	.. tabs::

	.. group-tab:: Linux

	1. Set-up the needed tools and environment:

	.. code-block:: bash

	sudo apt-get install -y doxygen graphviz default-jre
	mkdir ~/plantuml
	curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
	export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar

	# For PDF generation
	sudo apt-get install -y doxygen-latex

	# Additional Python dependencies for documentation
	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:

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

	- 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:

	.. code-block:: bash

	cd <TF-M base folder>
	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

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

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

	.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
	.. _Doxygen: https://www.doxygen.nl

	--------------

	Copyright (c) 2017-2021, Arm Limited. All rights reserved.