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 the Documentation overview section in the 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 the Installing the documentation processors section in the Documentation Generation developer guide for information about installing the required tools to build the documentation and their supported versions.

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.

Documentation structure

All documentation build files are located in the doc/bridle folder. The bridle subfolder in that directory contains all .rst source files that are not directly related to a sample application or a library. Documentation for samples and libraries are provided in a README.rst or *.rst file in the same directory as the code.

Building the documentation output requires building output for all documentation sets. Currently, there are two sets: bridle, and zephyr. Since there are links from the bridle documentation set into other documentation sets, the other documentation sets must be built first.

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-html -b none -d build/bridle-doc
west build -t devicetree-html -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-html
ninja -C build/bridle-doc devicetree-html
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 references:

use west

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

direct calls

ninja -C build/bridle-doc clean-kconfig

To clean the build folders for the Devicetree bindings:

use west

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

direct calls

ninja -C build/bridle-doc clean-devicetree

To clean the build folders for the Zephyr documentation:

use west

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

direct calls

ninja -C build/bridle-doc clean-zephyr

To clean the build folders for Bridle documentation:

use west

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

direct calls

ninja -C build/bridle-doc clean-bridle

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