MCUXpresso SDK Documentation
Open on Repo Open an Issue
Source (.md/.rst) Page PDF (.pdf)

Documentation generation

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:

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

Build TF-M Reference Manual#

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

cd <TF-M base folder>
cmake -S docs -B build_docs
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.

cd <TF-M base folder>
cmake -S docs -B build_docs
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.

# 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

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.

Contents