How Open vSwitch’s Documentation Works

This document provides a brief overview on how the documentation build system within Open vSwitch works. This is intended to maximize the “bus factor” and share best practices with other projects.

reStructuredText and Sphinx

Nearly all of Open vSwitch’s documentation is written in reStructuredText, with man pages being the sole exception. Of this documentation, most of it is fed into Sphinx, which provides not only the ability to convert rST to a variety of other output formats but also allows for things like cross-referencing and indexing. for more information on the two, refer to the Documentation Style.

ovs-sphinx-theme

The documentation uses its own theme, ovs-sphinx-theme, which can be found on GitHub and is published on pypi. This is packaged separately from Open vSwitch itself to ensure all documentation gets the latest version of the theme (assuming there are no major version bumps in that package). If building locally and the package is installed, it will be used. If the package is not installed, Sphinx will fallback to the default theme.

The package is currently maintained by Stephen Finucane and Russell Bryant.

Read the Docs

The documentation is hosted on readthedocs.org and a CNAME redirect is in place to allow access from docs.openvswitch.org. Read the Docs provides a couple of nifty features for us, such as automatic building of docs whenever there are changes and versioning of documentation.

The Read the Docs project is currently maintained by Stephen Finucane, Russell Bryant and Ben Pfaff.

openvswitch.org

The sources for openvswitch.org are maintained separately from docs.openvswitch.org. For modifications to this site, refer to the GitHub project.