Build Process

Read the Docs Online

The file .readthedocs.yaml in the main folder of the repository configures the Read the Docs build process. There is really nothing special in this file for this project. After installing all the necessary packages, Read the Docs starts the Sphinx building process. Here we have to take a closer look at the docs/conf.py file. Besides the general Sphinx configuration, there is this code snippet that is only executed on the Read the Docs build server:

 1read_the_docs_build_folder = Path(os.environ.get("READTHEDOCS_OUTPUT", None))
 2input_dir = ".."
 3output_dir = get_rtd_output_dir()
 4output_dir.mkdir(parents=True, exist_ok=True)
 5configureDoxyfile(input_dir, output_dir.absolute().as_posix())
 6
 7cwd = os.path.dirname(os.path.realpath(__file__))
 8subprocess.call(["doxygen", "Doxyfile"], shell=False, cwd=cwd)
 9subprocess.call(
10    ["doxysphinx", "build", ".", read_the_docs_build_folder / "html", "Doxyfile"],
11    shell=False,
12    cwd=cwd,
13)

In the first five lines the input and output dir of doxygen is specified and the doxygen configuration file is generated using the configureDoxyfile() function. In line 8 doxygen is executed on the Read the Docs server with the newly created Doxyfile as input. To ensure the correct usage of relative paths, the current file directory cwd (line 7) is set as the current working directory. Similar to lines 9-13, doxysphinx is executed on the server, which will create the necessary *.rst files for the doxygen documentation such that they will be integrated in the Sphinx command.

Doxylink is configured the same on a local build as well as on a Read the Docs build:

1doxylink = {
2    lib_name: (
3        lib_name + "/html/tagfile.xml",
4        lib_name + "/html"
5        )
6    }

The first value (key) lib_name will be used as an indicator for the linking in the *.rst files. As already shown in the Home page with doxylink a direct link to the doxygen documentation can be generated. For example, :lib_name:`Cat` generates Cat, where lib_name = animals in this project. The first parameter in the mapping specifies the path to the tag file of the doxygen documentation. The second parameter has to be an absolute path or a path relative to the Sphinx output directory of the created doxygen documentation.

After processing, the configuration file docs/conf.py Sphinx is executed on the Read the Docs server. When the build was successful the generated html files in $READTHEDOCS_OUTPUT/html will serve as the online documentation, where the file index.html, which is automatically generated by Sphinx is the home page of the documentation.

Without CMake

If you want to create the documentation locally without CMake you could also run the necessary commands in a terminal. Before you do that, it is important to create your own local doxygen configuration file, since this is neither done by CMake nor the conf.py file. In the following, it is assumed that a file Doxyfile is created based on the given file Doxyfile.in, similar to the automatic process described above.

Running doxygen

The following command should be executed in the docs folder of this project. Replace ${DOXYFILE} with your doxygen configuration file, which is in this example Doxyfile.

doxygen ${DOXYFILE}
doxygen Doyxfile

Note that it is assumed in the following, that the doxygen output folder is located in docs/animals.

Running doxysphinx

Now doxysphinx can be executed. After the build command follows the sphinx source directory ${SPHINX_SOURCE}, which is in this example the docs folder. Note that this command in this example should also be executed in the docs folder of this project, so the docs is here represented as a dot .. It is followed by the sphinx build directory ${SPHINX_BUILD}, which is replaced in the example by the folder docs/sphinx in an out-of-source build folder.

doxysphinx build ${SPHINX_SOURCE} ${SPHINX_BUILD} ${DOXYFILE}
doxysphinx build . ../../build/docs/sphinx Doxyfile

Using CMake

In this project you will also find a CMake build process for the local generation of the documentation. All the mentioned build steps in the Without CMake section will be automatically executed during the build process. The docs/CMakeLists.txt has many helpful commands, so it will be narrowed down here to the general idea used in this CMake build process.

Using the find_package() command from CMake, CMake looks for the three executables doxygen, doxysphinx and sphinx-build. While CMake comes up with a FindDoxygen.cmake file directly, the two other files, FindDoxysphinx and FindSphinx, are given in the cmake folder of this repository.

Note

The cmake folder is added to the CMAKE_MODULE_PATH in the main CMakeLists.txt file.

All three commands are executed with the given arguments above. This will be achieved by adding these as a custom command using CMakes function add_custom_command(). And, depending on the output of these custom commands, for every custom command, a corresponding custom CMake target is created is using add_custom_target(). The custom command for doxygen depends on the public header files of the library. This means, that it will only be executed (and therefore the target will only be executed) when one of these header files changes. The same is done for the doxysphinx command, which will only be executed when one of these public header files changes. Similar to the sphinx-build command, it depends on the used *.rst files for the documentation. These are either the *.rst files created by the doxysphinx command or the ones written by the developer in the docs folder.

Note

Using the approach described above, only sphinx-build will be executed when one of the *.rst files in the docs folder, for example docs/index.rst, changes. When one of the public header files in the library changes, all three commands will be executed. Code changes that do not affect public header files won’t trigger any execution of the three commands.