If you need urgent consulting help click here

Documentation Generation

These instructions will walk you through generating the Zephyr Project’s documentation on your local system using the same documentation sources as we use to create the online documentation found at https://docs.zephyrproject.org

Documentation overview

Zephyr Project content is written using the reStructuredText markup language (.rst file extension) with Sphinx extensions, and processed using Sphinx to create a formatted stand-alone website. Developers can view this content either in its raw form as .rst markup files, or you can generate the HTML content and view it with a web browser directly on your workstation. This same .rst content is also fed into the Zephyr Project’s public website documentation area (with a different theme applied).

You can read details about reStructuredText, and Sphinx from their respective websites.

The project’s documentation contains the following items:

  • ReStructuredText source files used to generate documentation found at the https://docs.zephyrproject.org website. Most of the reStructuredText sources are found in the /doc directory, but others are stored within the code source tree near their specific component (such as /samples and /boards)

  • Doxygen-generated material used to create all API-specific documents also found at https://docs.zephyrproject.org

  • Script-generated material for kernel configuration options based on Kconfig files found in the source code tree

digraph { rankdir=LR images [shape="rectangle" label=".png, .jpg\nimages"] rst [shape="rectangle" label="restructuredText\nfiles"] conf [shape="rectangle" label="conf.py\nconfiguration"] rtd [shape="rectangle" label="read-the-docs\ntheme"] header [shape="rectangle" label="c header\ncomments"] xml [shape="rectangle" label="XML"] html [shape="rectangle" label="HTML\nweb site"] sphinx[shape="ellipse" label="sphinx +\nbreathe,\ndocutils"] images -> sphinx rst -> sphinx conf -> sphinx header -> doxygen doxygen -> xml xml-> sphinx rtd -> sphinx sphinx -> html }

Fig. 36 Schematic of the documentation build process

The reStructuredText files are processed by the Sphinx documentation system, and make use of the breathe extension for including the doxygen-generated API material. Additional tools are required to generate the documentation locally, as described in the following sections.

Installing the documentation processors

Our documentation processing has been tested to run with:

  • Doxygen version 1.8.13

  • Graphviz 2.43

  • Latexmk version 4.56

  • All Python dependencies listed in the repository file scripts/requirements-doc.txt

In order to install the documentation tools, first install Zephyr as described in Getting Started Guide. Then install additional tools that are only required to generate the documentation, as described below:

Linux

macOS

Windows

On Ubuntu Linux:

sudo apt-get install --no-install-recommends doxygen graphviz librsvg2-bin \
texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended

On Fedora Linux:

sudo dnf install doxygen graphviz texlive-latex latexmk \
texlive-collection-fontsrecommended librsvg2-tools

On Clear Linux:

sudo swupd bundle-add texlive graphviz

On Arch Linux:

sudo pacman -S graphviz doxygen librsvg texlive-core texlive-bin \
texlive-latexextra texlive-fontsextra

Use brew and tlmgr to install the tools:

brew install doxygen graphviz mactex librsvg
tlmgr install latexmk
tlmgr install collection-fontsrecommended

Open a cmd.exe window as Administrator and run the following command:

choco install doxygen.install graphviz strawberryperl miktex rsvg-convert

Note

On Windows, the Sphinx executable sphinx-build.exe is placed in the Scripts folder of your Python installation path. Depending on how you have installed Python, you might need to add this folder to your PATH environment variable. Follow the instructions in Windows Python Path to add those if needed.

Documentation presentation theme

Sphinx supports easy customization of the generated documentation appearance through the use of themes. Replace the theme files and do another make html and the output layout and style is changed. The read-the-docs theme is installed as part of the Get Zephyr and install Python dependencies step you took in the getting started guide.

Running the documentation processors

The /doc directory in your cloned copy of the Zephyr project git repo has all the .rst source files, extra tools, and Makefile for generating a local copy of the Zephyr project’s technical documentation. Assuming the local Zephyr project copy is in a folder zephyr in your home folder, here are the commands to generate the html content locally:

# On Linux/macOS
cd ~/zephyr/doc
# On Windows
cd %userprofile%\zephyr\doc

# Use cmake to configure a Ninja-based build system:
cmake -GNinja -B_build .

# Enter the build directory
cd _build

# To generate HTML output, run ninja on the generated build system:
ninja html
# If you modify or add .rst files, run ninja again:
ninja html

# To generate PDF output, run ninja on the generated build system:
ninja pdf

Warning

The documentation build system creates copies in the build directory of every .rst file used to generate the documentation, along with dependencies referenced by those .rst files.

This means that Sphinx warnings and errors refer to the copies, and not the version-controlled original files in Zephyr. Be careful to make sure you don’t accidentally edit the copy of the file in an error message, as these changes will not be saved.

Depending on your development system, it will take up to 15 minutes to collect and generate the HTML content. When done, you can view the HTML output with your browser started at doc/_build/html/index.html and if generated, the PDF file is available at doc/_build/pdf/zephyr.pdf.

If you want to build the documentation from scratch just delete the contents of the build folder and run cmake and then ninja again.

Note

If you add or remove a file from the documentation, you need to re-run CMake.

On Unix platforms a convenience Makefile at the doc folder of the Zephyr repository can be used to build the documentation directly from there:

cd ~/zephyr/doc

# To generate HTML output
make html

# To generate PDF output
make pdf

Filtering expected warnings

There are some known issues with Sphinx/Breathe that generate Sphinx warnings even though the input is valid C code. While these issues are being considered for fixing we have created a Sphinx extension that allows to filter them out based on a set of regular expressions. The extension is named zephyr.warnings_filter and it is located at doc/_extensions/zephyr/warnings_filter.py. The warnings to be filtered out can be added to the doc/known-warnings.txt file.

The most common warning reported by Sphinx/Breathe is related to duplicate C declarations. This warning may be caused by different Sphinx/Breathe issues:

  • Multiple declarations of the same object are not supported

  • Different objects (e.g. a struct and a function) can not share the same name

  • Nested elements (e.g. in a struct or union) can not share the same name

Developer-mode Document Building

When making and testing major changes to the documentation, we provide an option to temporarily stub-out the auto-generated Devicetree bindings documentation so the doc build process runs faster.

To enable this mode, set the following option when invoking cmake:

-DDT_TURBO_MODE=1

or invoke make with the following target:

cd ~/zephyr

# To generate HTML output without detailed Kconfig
make html-fast

Linking external Doxygen projects against Zephyr

External projects that build upon Zephyr functionality and wish to refer to Zephyr documentation in Doxygen (through the use of @ref), can utilize the tag file exported at zephyr.tag

Once downloaded, the tag file can be used in a custom doxyfile.in as follows:

TAGFILES = "/path/to/zephyr.tag=https://docs.zephyrproject.org/latest/doxygen/html/"

For additional information refer to Doxygen External Documentation.