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.
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: +
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
variables of the
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
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.
make html to generate html documentation in
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.txtfile, which should be alphabetized using
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
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
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
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.