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
Running doxylink and Sphinx
Doxylink will automatically be configured in the docs/conf.py
when Sphinx
is executed; see above. So it is sufficient now to run the Sphinx
build command sphinx-build
. The argument -b html
specifies HTML files as output. In the current sphinx version, a HTML build is the default, so this is not absolutely necessary. Thereafter, similar to the doxysphinx command above, the sphinx source directory ${SPHINX_SOURCE}
and the sphinx build directory ${SPHINX_BUILD}
follows. Again, in this example, it is assumed that the command is executed in the docs
folder.
sphinx-build -b html ${SPHINX_SOURCE} ${SPHINX_BUILD}
sphinx-build -b html . ../../build/docs/sphinx
That’s it. Now you should find your documentation in the specified ${SPHINX_BUILD}
directory. Open the index.html
file to get to the documentation home page.
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.