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 Install the Necessary Packages
  24 ===============================
  25
  26 Before building the docs there are some packages that are needed. To install
  27 these packages on ubuntu execute the following.
  28
  29 .. code-block:: console
  30
  31    $ sudo apt-get install python3-all python3-setuptools python3-pip
  32
  33
  34 Create a Virtual Environment using virtualenv
  35 ===============================================
  36
  37 For more information on how to use the Python virtual environment check out
  38 `Installing packages using pip and virtualenv`_.
  39
  40 .. _`Installing packages using pip and virtualenv`: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/
  41
  42 In the vpp root directory on your system, run:
  43
  44 .. code-block:: console
  45
  46    $ make docs-venv
  47
  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.
  50
  51 Build the html files
  52 ======================
  53
  54 Build the html **index.html** file:
  55
  56 .. code-block:: console
  57
  58    $ make docs
  59
  60 Clean the environment
  61 ======================
  62
  63 Delete all the generated files with the following:
  64
  65 .. code-block:: console
  66
  67    $ make docs-clean
  68
  69 View the results
  70 =================
  71
  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.
  74
  75 .. figure:: /_images/htmlBuild.png
  76    :alt: Figure: My directory containing the index.html file
  77    :scale: 35%
  78    :align: center
  79
  80 Whenever you make changes to your **.rst** files that you want to see, repeat this build process.
  81
  82 .. note::
  83
  84    To exit from the virtual environment execute:
  85
  86 .. code-block:: console
  87
  88    $ deactivate
  89
  90 Getting your documents reviewed and merged
  91 ==========================================
  92
  93 VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
  94 to get your changes reviewed and merged.