Documentation Guide

Writing Documentation

Docs are generated using Sphinx.

Documentation is written in reStructuredText - see this link for the basic format.

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: =, - ", ', ^.

Referencing other Documentation

Other Sphinx-built documentation, both ONF and non-ONF can be linked to using Intersphinx.

You can see all link targets available on a remote Sphinx’s docs by running:

python -msphinx.ext.intersphinx http://otherdocs/objects.inv

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 sphinx-multiversion to build multiple versions of the site.

Adding Images and Diagrams

There are multiple ways to add images and diagrams to the documentation. Generally, you should prefer using SVG images, as these can be scaled to any size without quality loss.

If you’re creating diagrams, there are multiple tools available. Graphviz can render inline text-based graphs definitions and diagrams within the documentation, and is best for simple diagrams.

More complex diagrams can be created in Diagrams.net/Draw.io format. When saving these diagrams, use the SVG format, and check the “Include a copy of my diagram”. This will let someone open the SVG later directly from the documentation and edit it, without any loss in functionality or quality.

The last resort is to use raster images. If they’re drawings or screen captures, use the PNG format. Consider compressing them with a tool like OptiPNG, or pngquant. If it’s a photograph, use JPEG.