| ######################## |
| 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. |
| |
| Support for document generation in the build environment is not mandatory. |
| Missing document generation tools will not block building the TF-M firmware. |
| |
| *************************** |
| 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 |
| |
| 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 . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521 |
| cmake --build cmake_doc -- 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 |
| |
| 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 . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521 |
| cmake --build cmake_doc -- tfm_docs_refman_html tfm_docs_refman_pdf |
| |
| The documentation files will be available under the directory ``cmake_doc\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 |
| |
| .. 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 . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521 |
| cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf |
| |
| The documentation files will be available under the directory ``cmake_doc/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 . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521 |
| cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf |
| |
| The documentation files will be available under the directory ``cmake_doc\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.* |