docs/gettingstarted/writingdocs/buildingrst.rst

   1 .. _buildingrst:
   2
   3 **************************
   4 Creating VPP Documents
   5 **************************
   6
   7 These instructions show how the VPP documentation sources are built.
   8
   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/>`_.
  11
  12 Get the VPP sources
  13 =====================
  14
  15 Start with a clone of the vpp repository.
  16
  17 .. code-block:: console
  18
  19    $ git clone https://gerrit.fd.io/r/vpp
  20    $ cd vpp
  21
  22
  23 Create a Virtual Environment using virtualenv
  24 ===============================================
  25
  26 For more information on how to use the Python virtual environment check out
  27 `Installing packages using pip and virtualenv`_.
  28
  29 .. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/
  30
  31 In the vpp root directory on your system, run:
  32
  33 .. code-block:: console
  34
  35    $ python -m pip install --user virtualenv
  36    $ python -m virtualenv env
  37    $ source env/bin/activate
  38    $ pip install -r docs/etc/requirements.txt
  39    $ cd docs
  40
  41 Which installs all the required applications into it's own, isolated, virtual environment, so as to not
  42 interfere with other builds that may use different versions of software.
  43
  44 Build the html files
  45 ======================
  46
  47 Be sure you are in your vpp-docs/docs directory, since that is where Sphinx will look for your **conf.py**
  48 file, and build the **.rst** files into an **index.html** file:
  49
  50 .. code-block:: console
  51
  52    $ make html
  53
  54 View the results
  55 =================
  56
  57 | If there are no errors during the build process, you should now have an **index.html** file in your
  58 | **vpp/docs/_build/html** directory, which you can then view in your browser.
  59
  60 .. figure:: /_images/htmlBuild.png
  61    :alt: Figure: My directory containing the index.html file
  62    :scale: 35%
  63    :align: center
  64
  65 Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
  66
  67 .. note::
  68
  69    To exit from the virtual environment execute:
  70
  71 .. code-block:: console
  72
  73    $ deactivate
  74
  75 Getting your documents reviewed and merged
  76 ==========================================
  77
  78 VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
  79 to get your changes reviewed and merged.