Building Bridle documentation

The Bridle documentation is written using the reStructuredText markup language (.rst file extension) with Sphinx extensions and processed using Sphinx. API documentation is included from Doxygen comments.

See Documentation overview in the Zephyr Documentation Generation developer guide for information about reStructuredText.

Before you start 

Before you can build the documentation, install Bridle as described in Installing Bridle manually. Make sure that you have installed the required Python dependencies. See Installing the documentation processors in the Zephyr Documentation Generation developer guide for information about installing the required tools to build the documentation and their supported versions.

The following tool versions have been tested to work:

Tool	Min. Version
Sphinx	~=7.4 (see Python dependencies)
Doxygen	1.9.2
Graphviz (dot)	2.42
MscGen	0.20

Complete the following steps to install the required tools:

If you have not done so already, install Bridle as described in Installing Bridle manually.
Install or update all required Python dependencies.
The installation process of all other tools is different depending on your operating system.
To install the required tools on Linux, complete the following steps:

Common to all Linux installations, install the Python dependencies required to build the documentation:
pip install -U -r ~/zephyrproject/zephyr/doc/requirements.txt
On Ubuntu Linux:
sudo apt-get install --no-install-recommends doxygen graphviz librsvg2-bin \ texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended imagemagick
On Fedora Linux:
sudo dnf install doxygen graphviz texlive-latex latexmk \ texlive-collection-fontsrecommended librsvg2-tools ImageMagick
On Clear Linux:
sudo swupd bundle-add texlive graphviz ImageMagick
On Arch Linux:
sudo pacman -S graphviz doxygen librsvg texlive-core texlive-bin \ texlive-latexextra texlive-fontsextra imagemagick
To upgrade and install additional required tools on Ubuntu, complete the following steps:
1. Setup the apt environment to install system packages from the TiaC Systems Doxygen PPA:
  sudo add-apt-repository ppa:tiac-systems/doxygen sudo apt update
2. Use apt to install additional required dependencies:
  sudo apt install --no-install-recommends doxygen graphviz mscgen
3. Verify the versions of the main dependencies installed on your system by entering:
  sphinx-build --version doxygen --version dot -V mscgen -V
  Check those against the versions in the table in the beginning of this section.
To install the required tools on macOS, complete the following steps:

Install the Python dependencies required to build the documentation:
pip install -U -r ~/zephyrproject/zephyr/doc/requirements.txt
Use brew and tlmgr to install the tools:
brew install doxygen graphviz mactex librsvg imagemagick tlmgr install latexmk tlmgr install collection-fontsrecommended
Use brew to install the additional tool mscgen:
brew install mscgen
To install the required tools on Windows, complete the following steps:

Install the Python dependencies required to build the documentation:
pip install -U -r %HOMEPATH$\zephyrproject\zephyr\doc\requirements.txt
Open a cmd.exe window as Administrator and run the following command:
choco install doxygen.install graphviz strawberryperl miktex rsvg-convert imagemagick
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.

Download, inspect (MD5: a04b258bb459f894ed8ec2c7896fa346) and execute Michael McTernan’s Windows installer for mscgen from: https://www.mcternan.me.uk/mscgen/software/mscgen_0.20.exe

Building documentation output 

There are two different methods available, a quick way via west and a way with direct calls to the necessary configuration and build tools.

use west:

west build --cmake-only -b none -d build/bridle-doc bridle/doc
west build -t zephyr-doxygen -b none -d build/bridle-doc
west build -t bridle-doxygen -b none -d build/bridle-doc
west build -t build-all -b none -d build/bridle-doc

direct calls:

Complete the following steps to build the documentation output:

Load the environment setting for Zephyr builds.
- On Linux or macOS:
```
source zephyr/zephyr-env.sh
```
- On Windows:
```
zephyr\zephyr-env.cmd
```

Generate the Ninja build files and build the complete Bridle (3rd) documentation:

cmake -Bbuild/bridle-doc -GNinja bridle/doc
ninja -Cbuild/bridle-doc zephyr-doxygen
ninja -Cbuild/bridle-doc bridle-doxygen
ninja -Cbuild/bridle-doc build-all

This command will build all documentation sets and can take up to 20 minutes.

Alternatively, if you want to build each documentation set separately, complete the following steps. Generate the Ninja build files and build the Kconfig Reference and Devicetree Bindings (1st), Zephyr (2nd), and Bridle (3rd) documentation:

use west:

# Use west to configure a Ninja-based buildsystem with cmake:
west build --cmake-only -b none -d build/bridle-doc bridle/doc

# Now run west on the generated build system:
west build -t kconfig -b none -d build/bridle-doc
west build -t devicetree -b none -d build/bridle-doc
west build -t zephyr-doxygen -b none -d build/bridle-doc
west build -t zephyr -b none -d build/bridle-doc
west build -t bridle-doxygen -b none -d build/bridle-doc
west build -t bridle -b none -d build/bridle-doc

direct calls:

# Use cmake to configure a Ninja-based buildsystem:
cmake -Bbuild/bridle-doc -GNinja bridle/doc

# Now run the build tool on the generated build system:
ninja -Cbuild/bridle-doc kconfig
ninja -Cbuild/bridle-doc devicetree
ninja -Cbuild/bridle-doc zephyr-doxygen
ninja -Cbuild/bridle-doc zephyr
ninja -Cbuild/bridle-doc bridle-doxygen
ninja -Cbuild/bridle-doc bridle

It is important to keep the order of build targets!

The documentation output is written to build/bridle-doc/html or build/bridle-doc/doxygen/*/html in case of the standalone API documentation of Zephyr and Bride. Double-click the index.html file to display the documentation in your browser or type in:

firefox build/bridle-doc/html/index.html &
firefox build/bridle-doc/doxygen/zephyr/html/index.html &
firefox build/bridle-doc/doxygen/bridle/html/index.html &

Tip

If you modify or add RST files, you only need to rerun the steps that build the respective documentation: 2nd target in step 3 if you modified the Zephyr documentation, 3rd target in step 3 if you modified Bridle documentation.

If you open up a new command prompt, you must repeat step 2 or complete step 3.

Serve documentation locally 

Allow running from localhost; local build can be served with Python HTTP server module:

python -m http.server -b localhost -d build/bridle-doc/html 4711 &

Now you can browse locally with:

firefox http://localhost:4711/index.html &

Caching and cleaning 

To speed up the documentation build, Sphinx processes only those files that have been changed since the last build. In addition, RST files are copied to a different location during the build process. This mechanism can cause outdated or deleted files to be used in the build, or the navigation to not be updated as expected.

If you experience any such problems, clean the build folders before you run the documentation build. Note that this will cause the documentation to be built from scratch, which takes a considerable time.

To clean the build folders for the Kconfig Reference:

use west:

west build -t kconfig-clean -b none -d build/bridle-doc

direct calls:

ninja -C build/bridle-doc kconfig-clean

To clean the build folders for the Devicetree Bindings:

use west:

west build -t devicetree-clean -b none -d build/bridle-doc

direct calls:

ninja -C build/bridle-doc devicetree-clean

To clean the build folders for the Zephyr RTOS documentation:

use west:

west build -t zephyr-clean -b none -d build/bridle-doc

direct calls:

ninja -C build/bridle-doc zephyr-clean

To clean the build folders for Bridle documentation:

use west:

west build -t bridle-clean -b none -d build/bridle-doc

direct calls:

ninja -C build/bridle-doc bridle-clean

To clean all the documentation sets build files:

use west:

west build -t clean -b none -d build/bridle-doc

direct calls:

ninja -C build/bridle-doc clean

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

direct calls:

rm -rf build/bridle-doc

Testing different versions locally 

Documentation sets for different versions of the Bridle are defined in the doc/versions.json file. This file is used to display the version drop-down in the top-left corner of the documentation.

The version drop-down is displayed only if the documentation files are organized in the required folder structure and the documentation is hosted on a web server. To test the version drop-down locally, complete the following steps:

In the documentation build folder (for example, build/bridle-doc), rename the html folder to latest.
Open a command window in the documentation build folder and enter the following command to start a Python web server:
```
python -m http.server
```
Alternative set the documentation build folder as document root:
```
python -m http.server -d build/bridle-doc
```
Access http://localhost:8000/latest/index.html with your browser to see the documentation.

To add other versions of the documentation to your local documentation output, build the versions from a tagged release and rename the html folder to the respective version (for example, 3.7.0).

Dealing with warnings 

When building the documentation, all warnings are regarded as errors, so they will make the documentation build fail.

However, there are some known issues with Sphinx and Breathe that generate Sphinx warnings even though the input is valid C code. To deal with such unavoidable warnings, Zephyr provides the Sphinx extension zephyr.warnings_filter that filters out warnings based on a set of regular expressions. You can find the extension together with usage details at workspace/zephyr/doc/_extensions/zephyr/warnings_filter.py.

The configuration file that defines the expected warnings for the Bridle documentation set is located at workspace/doc/bridle/known-warnings.txt. It contains regular expressions to filter out warnings related to duplicate C declarations. These warnings are caused by different objects (for example, a struct and a function or nested elements) sharing the same name.

Building Bridle documentation

Before you start

Building documentation output

Serve documentation locally

Caching and cleaning

Testing different versions locally

Dealing with warnings

Before you start 

Building documentation output 

Serve documentation locally 

Caching and cleaning 

Testing different versions locally 

Dealing with warnings 