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 python3-sphinx

Similarly, on RHEL/Fedora run:

$ sudo dnf install python3-sphinx

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

$ python3 -m venv .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

Before building documentation, the OVN build system must be configured. This requires the OVS submodule to be prepared first:

$ git submodule update --init
$ cd ovs
$ ./boot.sh && ./configure
$ cd ..
$ ./boot.sh && ./configure

Once Sphinx is installed and OVN is configured, 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 subtle issues such as style or grammar errors. 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.

To build the man page distribution documents (as used by the OVN website):

$ make dist-docs