blob: 37dce1514e3ba8e033db501bdcad3078096f9d16 [file] [log] [blame]
Documentation Guide
Writing Documentation
Docs are generated using `Sphinx <>`_.
Documentation can be written in `reStructuredText
<>`_ (``.rst``) or
`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
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
<>`_ 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.
supports many standard graph types.