Creating VPP Documents

These instructions show how the VPP documentation sources are built.

The VPP Documents are written using reStructuredText (rst), or markdown (md). These files are then built using the Sphinx build system Sphinx.

Get the VPP sources

Start with a clone of the vpp repository.

$ git clone https://gerrit.fd.io/r/vpp
$ cd vpp

Install the Necessary Packages

Before building the docs there are some packages that are needed. To install these packages on ubuntu execute the following.

$ sudo apt-get install python3-all python3-setuptools python3-pip

Create a Virtual Environment using virtualenv

For more information on how to use the Python virtual environment check out Installing packages using pip and virtualenv.

In the vpp root directory on your system, run:

$ make docs-venv

Which installs all the required applications into it’s own, isolated, virtual environment, so as to not interfere with other builds that may use different versions of software.

Build the html files

Build the html index.html file:

$ make docs

Clean the environment

Delete all the generated files with the following:

$ make docs-clean

View the results

If there are no errors during the build process, you should now have an index.html file in your

vpp/docs/_build/html directory, which you can then view in your browser.

Whenever you make changes to your .rst files that you want to see, repeat this build process.

Note

To exit from the virtual environment execute:

$ deactivate

Getting your documents reviewed and merged

VPP documents are reviewed and merged like and other source code. Refer to Getting a Patch Reviewed to get your changes reviewed and merged.