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    $ make docs-venv
  36
  37 Which installs all the required applications into it's own, isolated, virtual environment, so as to not
  38 interfere with other builds that may use different versions of software.
  39
  40 Build the html files
  41 ======================
  42
  43 Build the html **index.html** file:
  44
  45 .. code-block:: console
  46
  47    $ make docs
  48
  49 Clean the environment
  50 ======================
  51
  52 Delete all the generated files with the following:
  53
  54 .. code-block:: console
  55
  56    $ make docs-clean
  57
  58 View the results
  59 =================
  60
  61 | If there are no errors during the build process, you should now have an **index.html** file in your
  62 | **vpp/docs/_build/html** directory, which you can then view in your browser.
  63
  64 .. figure:: /_images/htmlBuild.png
  65    :alt: Figure: My directory containing the index.html file
  66    :scale: 35%
  67    :align: center
  68
  69 Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
  70
  71 .. note::
  72
  73    To exit from the virtual environment execute:
  74
  75 .. code-block:: console
  76
  77    $ deactivate
  78
  79 Getting your documents reviewed and merged
  80 ==========================================
  81
  82 VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
  83 to get your changes reviewed and merged.