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:

Complete the following steps to install the required tools:

  1. If you have not done so already, install the Bridle as described in Installing Bridle manually.

  2. Install or update all required Python dependencies.

  3. Install Doxygen.

  4. Install mscgen and make sure that the mscgen executable is in your PATH.

Note

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

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 build-all -b none -d build/bridle-doc
direct calls

Complete the following steps to build the documentation output:

  1. Load the environment setting for Zephyr builds.

    • On Windows:

      zephyr\zephyr-env.cmd

    • On Linux or macOS:

      source zephyr/zephyr-env.sh

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

    cmake -B build/bridle-doc -GNinja bridle/doc
ninja -C build/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 -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 -B build/bridle-doc -GNinja bridle/doc

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

It is important to keep the order of build targets!

The documentation output is written to build/bridle-doc/html. Double-click the index.html file to display the documentation in your browser or type in:

firefox build/bridle-doc/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:

  1. In the documentation build folder (for example, build/bridle-doc), rename the html folder to latest.

  2. 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

  3. 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, 2.7.1).

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.