doc

There are two documentation systems used. doxygen is used to generate either HTML or XML containing the technical API documentation. sphinx is used for separate documentation located in /doc and also to build the complete documentation in a consistent style.

Most of the time, you want to use a sphinx-based build.

doxygen

Note

You may notice doxygen runs seperate in CI as analyse/doxygen. Due to a bug in Doxygen warnings will be emitted when XML output is enabled. This job builds only HTML so that valid warnings can be caught and reported on by CI. https://bugzilla.gnome.org/show_bug.cgi?id=792676

When configuring with -DDOC:STRING=doxygen target doc will be added. The target will run doxygen over all source code. This generates HTML API documentation.

This will not run any sphinx-based jobs and therefore will not build any documentation stored in /doc.

When also configuring with -DWERROR:BOOL=ON all warnings generated by doxygen will be turned into errors.

Target doc_clean will also be added and removes build products and temporary files related to the doc target itself.

sphinx-based

When configuring with -DDOC:STRING=${BUILDER} where ${BUILDER} is not one of either OFF or doxygen target doc will be added. The target will then run sphinx with builder type ${BUILDER}.

doxygen will still be used to generate XML output for API documentation of source files. Said XML is then used to generate the final output.

When also configuring with -DWERROR:BOOL=ON all warnings generated by sphinx, but not doxygen, will be turned into errors.

By default sphinx caches both input and output files to speed things up. Target doc_nocache will force reading all source files, this ensures dynamic directives such as toctrees are updated properly while still caching things that haven’t changed properly.

Target doc_clean will also be added and removes build products and temporary files related to the doc target itself.

Refer to http://www.sphinx-doc.org/en/master/builders.html for builder details.