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 ``

`` through ``

``) 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.