Documentation Guide
===================

Writing Documentation
---------------------

Docs are generated using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.

Documentation can be written in `reStructuredText
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/>`_ (``.rst``)  or
`Markdown <https://daringfireball.net/projects/markdown/>`_ (``.md``), but
reStructuredText is preferred as that filetype supports features like embedded
diagrams and tables.

In reStructuredText documents, to create the section hierarchy (mapped in HTML
to ``<h1>`` through ``<h5>``) use these characters to underline headings in the
order given: ``=``, ``-`` ``"``, ``'``, ``^``.

Building the Docs
------------------

The documentation build process is stored in the ``Makefile``. Building docs
requires Python to be installed, and most steps will create a virtualenv
(``venv_docs``) which contains the required tools.  You may also need to
install the ``enchant`` C library using your system's package manager for the
spelling checker to function properly.

Run ``make html`` to generate html documentation in ``_build/html``.

To check the formatting of documentation, run ``make lint``. This will be done
in Jenkins to validate the documentation, so please do this before you create a
patchset.

To check spelling, run ``make spelling``. If there are additional words that
are correctly spelled but not in the dictionary (acronyms, trademarks, etc.)
please add them to the ``dict.txt`` file.

Creating new Versions of Docs
-----------------------------

To change the version shown on the built site, change the contents of the
``VERSION`` file.

There is a ``make multiversion`` target which will build all versions published
on the remote to ``_build``. This will use a fork of `sphinx-multiversion
<https://github.com/Holzhaus/sphinx-multiversion>`_ to build multiple versions
for the site.

Creating Graphs and Diagrams
----------------------------

Multiple tools are available to render inline text-based graphs definitions and
diagrams within the documentation. This is preferred over images as it's easier
to change and see changes over time as a diff.

`Graphviz
<https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html>`_
supports many standard graph types.