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

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:

$ python -m pip install --user virtualenv
$ python -m virtualenv env
$ source env/bin/activate
$ pip install -r docs/etc/requirements.txt
$ cd docs

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

Be sure you are in your vpp-docs/docs directory, since that is where Sphinx will look for your conf.py file, and build the .rst files into an index.html file:

$ make html

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.