3 **************************
5 **************************
7 These instructions show how the VPP documentation sources are built.
9 The VPP Documents are written using `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst),
10 or markdown (md). These files are then built using the Sphinx build system `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
15 Start with a clone of the vpp repository.
17 .. code-block:: console
19 $ git clone https://gerrit.fd.io/r/vpp
23 Install the Necessary Packages
24 ===============================
26 Before building the docs there are some packages that are needed. To install
27 these packages on ubuntu execute the following.
29 .. code-block:: console
31 $ sudo apt-get install python3-all python3-setuptools python3-pip
34 Create a Virtual Environment using virtualenv
35 ===============================================
37 For more information on how to use the Python virtual environment check out
38 `Installing packages using pip and virtualenv`_.
40 .. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/
42 In the vpp root directory on your system, run:
44 .. code-block:: console
48 Which installs all the required applications into it's own, isolated, virtual environment, so as to not
49 interfere with other builds that may use different versions of software.
52 ======================
54 Build the html **index.html** file:
56 .. code-block:: console
61 ======================
63 Delete all the generated files with the following:
65 .. code-block:: console
72 | If there are no errors during the build process, you should now have an **index.html** file in your
73 | **vpp/docs/_build/html** directory, which you can then view in your browser.
75 .. figure:: /_images/htmlBuild.png
76 :alt: Figure: My directory containing the index.html file
80 Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
84 To exit from the virtual environment execute:
86 .. code-block:: console
90 Getting your documents reviewed and merged
91 ==========================================
93 VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
94 to get your changes reviewed and merged.