Open Virtual Network (OVN) Documentation

This document describes how to build the OVN documentation for use offline. A continuously updated, online version can be found at docs.ovn.org.

Note

These instructions provide information on building the documentation locally. For information on writing documentation, refer to OVN Documentation Style

Build Requirements

As described in the OVN Documentation Style, the OVN documentation is written in reStructuredText and built with Sphinx. A detailed guide on installing Sphinx in many environments is available on the Sphinx website but, for most Linux distributions, you can install with your package manager. For example, on Debian/Ubuntu run:

$ sudo apt-get install python-sphinx

Similarly, on RHEL/Fedora run:

$ sudo dnf install python-sphinx

A requirements.txt is also provided in the /Documentation, should you wish to install using pip:

$ virtualenv .venv
$ source .venv/bin/activate
$ pip install -r Documentation/requirements.txt

Configuring

It’s unlikely that you’ll need to customize any aspect of the configuration. However, the Documentation/conf.py is the go-to place for all configuration. This file is well documented and further information is available on the Sphinx website.

Building

Once Sphinx installed, the documentation can be built using the provided Makefile targets:

$ make docs-check

Important

The docs-check target will fail if there are any syntax errors. However, it won’t catch more succint issues such as style or grammar issues. As a result, you should always inspect changes visually to ensure the result is as intended.

Once built, documentation is available in the /Documentation/_build folder. Open the root index.html to browse the documentation.