doc
===

The documentation system used is ``sphinx``. It is used for documentation
located in ``/doc`` and also to build the complete documentation in a consistent
style.

sphinx-based
------------

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

When also configuring with ``-DWERROR:BOOL=ON`` all warnings generated by
``sphinx`` 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.