docs/contributing/writingdocs.rst

   1 .. _buildingrst:
   2
   3 Writing VPP Documentation
   4 =========================
   5
   6 These instructions show how the VPP documentation sources are built.
   7
   8 The VPP Documents are written using `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ (rst),
   9 or markdown (md). These files are then built using the Sphinx build system `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
  10
  11 Building the docs
  12 -----------------
  13
  14 Start with a clone of the vpp repository.
  15
  16 .. code-block:: console
  17
  18    $ git clone https://gerrit.fd.io/r/vpp
  19    $ cd vpp
  20
  21 Build the html **index.html** file:
  22
  23 .. code-block:: console
  24
  25    $ make docs
  26
  27 Delete all the generated files with the following:
  28
  29 .. code-block:: console
  30
  31    $ make docs-clean
  32
  33 View the results
  34 ----------------
  35
  36 If there are no errors during the build process, you should now have an ``index.html`` file in your ``vpp/build-root/docs/html`` directory, which you can then view in your browser.
  37
  38 Whenever you make changes to your ``.rst`` files that you want to see, repeat this build process.
  39
  40 Writing Docs and merging
  41 ------------------------
  42
  43 Documentation should be added as ``.rst`` file in the ``./src/`` tree next to the code it refers to. A symlink should be added at the relevant place in the ``./docs`` folder and a link in the appropriate place in the tree.
  44
  45 To ensure documentation is correctly inserted, you can run
  46
  47 .. code-block:: console
  48
  49    $ ./extras/scripts/check_documentation.sh
  50
  51 VPP documents are reviewed and merged like and other source code. Refer to :ref:`gitreview`
  52 to get your changes reviewed and merged.