Skip to content

Latest commit

 

History

History
225 lines (160 loc) · 6.21 KB

documentation_generation.rst

File metadata and controls

225 lines (160 loc) · 6.21 KB
Raw

Documentation generation

Two documents are available for generation:

  • Reference Manual (HTML, PDF)
  • User Guide (HTML, PDF)

The documentation build is independent from building the binary artifacts.

Tools and building environment

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 v1.8 or later (for running PlantUML)
  • Sphinx and other python modules, listed in docs/requirements.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:

Linux

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

# Install the required Python modules
pip3 install --upgrade pip
cd trusted-firmware-m
pip3 install -r docs/requirements.txt

Windows

Download and install the following tools:

Set the environment variables, assuming that:

  • doxygen, dot, and MikTeX binaries are available on the PATH.
  • Java JVM is used from Arm DS installation.
set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin

# Install the required Python modules
pip3 install --upgrade pip
cd trusted-firmware-m
pip3 install -r docs\requirements.txt

Build TF-M Reference Manual

The Reference Manual will be generated in the build_docs/reference_manual.

Linux

cd <TF-M base folder>
cmake -S docs -B build_docs
cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf

Windows

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

Build TF-M User Guide

The User Manual will be available under the directory build_docs/user_guide.

Linux

cd <TF-M base folder>
cmake -S docs -B build_docs
cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf

Windows

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

Direct build using a command line tools

The direct build will build both user_guide and reference_manual.

Linux

# 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

Windows

# Command line tools is yet not available for Windows

Dependencies

@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

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