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.