758dc46072
Change-Id: I4766773779f8d5c30a24bfed48090d7305c80ec5 Signed-off-by: John DeNisco <jdenisco@cisco.com>
80 lines
2.3 KiB
ReStructuredText
80 lines
2.3 KiB
ReStructuredText
.. _buildingrst:
|
|
|
|
**************************
|
|
Creating VPP Documents
|
|
**************************
|
|
|
|
These instructions show how the VPP documentation sources are built.
|
|
|
|
The VPP Documents are written using `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst),
|
|
or markdown (md). These files are then built using the Sphinx build system `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
|
|
|
|
Get the VPP sources
|
|
=====================
|
|
|
|
Start with a clone of the vpp repository.
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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`_.
|
|
|
|
.. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/
|
|
|
|
In the vpp root directory on your system, run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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.
|
|
|
|
.. figure:: /_images/htmlBuild.png
|
|
:alt: Figure: My directory containing the index.html file
|
|
:scale: 35%
|
|
:align: center
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ deactivate
|
|
|
|
Getting your documents reviewed and merged
|
|
==========================================
|
|
|
|
VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
|
|
to get your changes reviewed and merged.
|