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
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 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 supports many standard graph types.
The blockdiag, nwdiag, and rackdiag, and seqdiag suites of tools can be used to create specific types of diagrams:
The styles applied to nodes and connections in these diagrams can be customized using attributes.