Building documentation¶
To build this documentation I follow the excelent guide provided by TartanLlama in Clear, Functional C++ Documentation with Sphinx + Breathe + Doxygen + CMake who also have a Github repository where there is an example to document C++ code.
The process is depicted in the next figure:
Building documentation process by Luighi Viton, 2020¶
According to this figure, the documentation is generated employing two main software: Doxygen and Sphinx.
Doxygen in by far the most common alternative when documenting C/C++ code, as it is able to strip out comments and based on them generate a corresponding documentation outputs ina variety of formats such as HTML, LaTeX, XML, etc.
However, to generate Doxygen documentation, all the information should be in the source code, which is unconvinient when you want to create custom pages and instructions. In addition to this, default themes in Doxygen are a bit outdated and appears to be old and not variety user friendly.
Then, to provide more flexibility, there is another tool named Sphinx, which is mainly use to generate documentation for Python projects. Although, it could not manage directly C/C++ code, there is an extension named Breathe which could connect with Doxygen, in the way that the generated output of Doxygen is taken by this extension and based on that, could generate the Sphinx documentation.
In addition to this, there is an online service called Read the Docs, which could publish the documentation based on the Sphinx source files. So, for this build the documentation we have two approaches: the local building documentation and the remote building documentation in the Read the Docs.
1. Local building process¶
The local building process makes use of cmake to automate
the steps required:
mkdir build
cd build
cmake ..
make Sphinx
Once the building process are completed succesfully, the generated output
is place in build\docs\docs\sphinx, so you can open the index.html
file in this folder to explore the documentation.
The control in the generation process is performed by cmake which have a
module to generate the Doxygen outputs based on
the Doxyfile.in file and a custom order for Sphinx
based on the conf.py file and the *.rst files
created to explain the whole documentation.
2. Documentation at ReadTheDocs¶
The documentation at ReadTheDocs is generated in a similar way as in the
local building process, however, it differs in the way that the file conf.py
has the control and is responsible to generate also the Doxygen outputs addition
create from them the Sphinx output documentation.
In general, all the changes uploaded to the respository are updated in the documentation as they are connected as a feature provided by the service, so as long as you have updated the documentation in the remote repository, it also will be updated in ReadTheDocs.