Documentation build process

Whenever the main branch of the sdk-nrf repository is updated or a pull request is made, a new version of the documentation is built and published. The following section describes the steps involved with building and publishing the documentation.

Building with Sphinx 

The nRF Connect SDK documentation uses the Sphinx framework to build the docsets for HTML. Sphinx primarily uses two files to work:

An entry point that serves as the top of the ToC tree and the root of the documentation (often named index.rst).
A Python file conf.py in which all further configuration of Sphinx is placed.

The command sphinx-build then needs to be run with the appropriate arguments. As with the rest of the nRF Connect SDK, this is handled by CMake.

CMake 

CMake not only creates a generator used to build the documentation, it also checks for the required binaries and dependencies and ensures that the docsets are built in the correct order. nrf/doc/CMakeLists.txt contains the function add_docset which is used to create targets for all the docsets. This includes the {docset}/ {docset}-all, {docset}-inventory/ {docset}-inventory-all, {docset}-linkcheck and {docset}-clean targets. The inventory targets create reference targets without building the documentation, providing a solution for any circular dependencies. Some docsets require additional source files to be generated before the docset can be built, like Zephyr’s device tree. In these cases a separate target is created and added as a dependency for the docset target.

External contents 

When sphinx-build is executed, a _build/{docset}/src directory is used as the source directory. The external_content extension executes before the build is initiated and copies every relevant documentation file into this folder. This is a “smart” copy, meaning that only new or modified files are copied to reduce build time. As this can change the file hierarchy somewhat, local link paths are modified during this process. Which files are copied is listed under external_content_contents in the conf.py file.

Intersphinx 

The nRF Connect SDK documentation consists of multiple docsets. The main docset is the nRF documentation, while the other docsets are pulled from their upstream versions. The only file that is needed to maintain for this, is a customized conf.py file located under doc/{docset-name}/. To be able to make references across docsets, the Sphinx extension Intersphinx is used, and local paths are configured under intersphinx_mapping in doc/nrf/conf.py. The upstream docsets are pulled using west.

Building and publishing the documentation 

The nRF Connect SDK documentation is currently hosted on docs.nordicsemi.com and is updated with every pull request that is merged into the main branch of the Git repository. Every pull request made is also hosted under the nRF_Connect_SDK_dev folder in developer.nordicsemi.com if the build workflow is successful. This is done through two chained GitHub actions, docbuild.yml and docpublish.yml.

Docbuild 

Whenever a pull request is created the docbuild workflow is triggered. This will checkout all the relevant repositories with west, install the necessary dependencies and build the documentation with CMake. After the documentation is built a cache file is created using doc/_scripts/cache_create.py which can be used locally to speed up builds.

Docpublish 

A successful completion of the docbuild workflow will trigger the docpublish workflow. It retrieves the artifacts from the previous workflow, uploads the cache files with doc/_scripts/cache_upload.py and then uploads the Sphinx-generated html files of the documentation to developer.nordicsemi.com where they are served. A link to the preview page is then added for pull requests.

Caching 

A cache is created in the docbuild workflow and uploaded in the docpublish workflow. When a build is initiated and caching is enabled, the builder will first check if the current version of the documentation is available in the cache and use it if it is. Caching is not enabled in the GitHub workflows, as they always process new versions to build.