Sphinx

Docs are generated using Sphinx using the reStructuredText syntax.

Sphinx was chosen because it’s widely used (Python official docs, Linux Kernel, Read the Docs, etc.), open source, actively maintained, has code highlighting, and a good client-side search implementation.

Writing Documentation

reStructuredText syntax references can be found here:

rST creates headings by underlining the heading with a series of symbol characters. There is no specific required order for these, but for consistency most ONF docs use the following symbols/order to represent heading levels:

H1: =
H2: -
H3: "
H4: '
H5: ^
H6: +

Linking within Documentation

Referencing other Documentation

Other Sphinx-built documentation, both ONF and non-ONF can be linked to using InterSphinx, which allows you to create links that will work even if the other site moves or reorganizes content.

New InterSphinx reference requires modifying the intersphinx_mapping variables of the conf.py file.

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

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

More information about InterSphinx:

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 choice for simple diagrams.

More complex diagrams can be created in Diagrams.net/Draw.io format, which is available as a standalone app, web app, or integrated with various other tools like Google Workspace. When saving these diagrams, use the SVG format, and check the Include a copy of my diagram box. This will let someone open the SVG later within Diagrams.net from file saved in the documentation and edit it without any loss in functionality or quality.

The last resort is to use raster (bitmap) images. If they’re drawings or screen captures, use the PNG format. Consider optimizing the PNG files with a tool like OptiPNG, or pngquant to save space and data transfer required.

If you need to include a photograph, use JPEG.

Building the Documentation

The documentation build process is stored in a Makefile. Building docs requires Python to be installed, and most steps will create a virtualenv (usually 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.

There is also a test target, make test, which will run all the following checks - this is what Jenkins does on patchset validation, so:

  • make lint: Check the formatting of documentation using doc8.

  • make license: Verifies licensing is correct using REUSE

  • make spelling: Checks spelling on all documentation. If there are additional words that are correctly spelled but not in the dictionary (acronyms, nouns, etc.) please add them to the dict.txt file, which should be alphabetized using sort

  • make linkcheck: Verifies that links in the document are working and accessible, using Sphinx’s built in linkcheck tool. If there are links that don’t work with this, please see the linkcheck_ignore section of conf.py.

Some sites may have the ability to build a PDF file of the documentation using make latexpdf. This requires that you have a recent LaTeX installation and latexmk installed.

Versioning Documentation

To change the version shown on the built site, change the contents of the VERSION file to be released SemVer version. This will create a tag on the repo.

Then when make multiversion target can be used which will build all versions tagged or branched on the remote to _build/multiversion. This will use a fork of sphinx-multiversion to build multiple versions and a menu on the site.

There are variables in conf.py to determine which tags/branches to build.