Building the nRF Connect SDK documentation

The nRF Connect SDK 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 developer guide for information about reStructuredText.

Before you start

Before you can build the documentation, you must install the required tools. 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 nRF Connect SDK as described in Installing the nRF Connect SDK 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.

Documentation structure

All documentation build files are located in the ncs/nrf/doc folder. The nrf 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 the output for all documentation sets. Following are the available documentation sets:

  • nrf: nRF Connect SDK

  • nrfx: nrfx

  • nrfxlib: nrfxlib

  • zephyr: Zephyr RTOS

  • mcuboot: MCUboot

  • kconfig: All available Kconfig options in the nRF Connect SDK

Since there are links from the nRF Connect SDK documentation set into other documentation sets, the documentation is built in a predefined order.

Building documentation output

Complete the following steps to build the documentation output:

  1. Open a shell and enter the doc folder ncs/nrf/doc.

    • On Windows:

      1. Navigate to ncs/nrf.

      2. Hold shift and right-click on the doc folder. Select Open command window here.

    • On Linux or macOS:

      1. Open a shell window.

      2. Navigate to ncs/nrf/doc. If the ncs folder is in your home directory, enter:

        cd ~/ncs/nrf/doc

  2. Generate the Ninja build files:

    cmake -GNinja -S. -B_build

  3. Enter the generated build folder:

    cd _build

  4. Run ninja to build the complete documentation:

    ninja

The documentation output is written to the doc/_build/html folder. Double-click the index.html file to display the documentation in your browser.

Alternatively, you can work with just a single documentation set, for example, nrf. The build system provides individual targets for such a purpose. If you have not built all documentation sets before, it is recommended to run the following command:

ninja docset-name-html-all

Here, docset-name is the name of the documentation set, for example, nrf. This target will build the documentation sets that are needed for docset-name.

On subsequent builds, it is recommended to just run the following command:

ninja docset-name-html

Alternatively, for subsequent builds, you can run the ninja command using the alias target docset-name instead of docset-name-html:

ninja docset-name

The last couple of targets mentioned in Documentation structure will only invoke the build for the corresponding documentation set (referred by docset-name), assuming that all of its dependencies are available.

Caching and cleaning

To speed up the documentation build, Sphinx processes only those files that have been changed since the last build. This mechanism can sometimes cause issues such as navigation not being updated correctly.

If you experience any of such issues, clean the build folders before you run the documentation build.

To clean all the build files:

ninja clean

To clean the build folders for a particular documentation set:

ninja docset-name-clean

Here, docset-name is the name of the documentation set, for example, nrf.

Different versions

Documentation sets for different versions of the nRF Connect SDK 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), 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

  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, 1.6.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 ncs/zephyr/doc/_extensions/zephyr/warnings_filter.py.

The configuration file that defines the expected warnings for the nrf documentation set is located at ncs/nrf/doc/nrf/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.