Docs are generated using Sphinx.
Documentation is written in reStructuredText, or in MyST Markdown.
In reStructuredText documents, to create the section hierarchy (mapped in HTML
<h5>) use the underline characters in this order:
The documentation build process is stored in the
Makefile. Building docs
requires Python3 to be installed, and most steps will automatically create
venv_docs) which contains the required tools.
make html will generate HTML formatted documentation in
_build/html, which you can view with a web browser.
Before submitting the docs or to verify the docs in CI workflow, run
test, which will check lint, spelling, and that links inside the site are not
broken. If there are additional words that are correctly spelled but not in the
dictionary (acronyms, trademarks, etc.) please add them to the
file. You may also need to install the
enchant C library using your
system’s package manager for the spelling checker to function properly.
Referencing other Documentation sites
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://other_docs_site/objects.inv
See the this document for Intersphinx examples.
Adding Documentation from other Repos
Documentation written in other git repos can be included in the documentation generated with this by performing the following steps:
Edit the space-separated list
Makefileto include the name of the other repo. These repos will be checked out into
reposand then copied into the main directory with the repo name (this is required for the versioning process to work).
Add the name of the repo to the
.gitignorefile so it won’t be checked in.
Add a line for the repo in
git_refswith the repo name, path, and git ref (usually
master) to be used.
Add the paths to the documentation files in the other repo to the
Build the docs with
make htmland verify that there aren’t any warnings and the docs have been added. If you need to exclude specific files from the docs, you should add them to the
Creating new versions of Docs
To change the version shown on the built site, change the contents of the
VERSION file. As a part of committing the code in the CI process, the
VERSION should be checked for uniqueness, and if it’s a SemVer version,
turned into a git tag.
There is a
make multiversion target which will build all git-tagged
versions and branches published on the remote to
_build. This will use a
fork of sphinx-multiversion to build multiple versions
for the site.
If you’re adding documentation from other repos and you want to hold to a
specific version, run
make freeze and put the output in the
file - this will cause that specific commit hash of the other repo to be
checked out when building the docs for a specific version.
Adding 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.
If you have hand-created charts, prefer to use diagrams.net/draw.io in
SVG format and embed the diagram source in the
image, which will allow it to be edited later.