docs/how-to-use-docs/documentation-example.rst

   1 How to create documentation for your OPNFV project
   2 ==================================================
   3
   4 this is the directory structure of the docs/ directory that can be found in the root of your project directory
   5
   6 .. code-block:: bash
   7
   8     ./etc
   9     ./etc/opnfv-logo.png
  10     ./etc/conf.py
  11     ./how-to-use-docs
  12     ./how-to-use-docs/documentation-example.rst
  13     ./how-to-use-docs/index.rst
  14
  15 To create your own documentation, Create any number of directories (depending on your need) and place in each of them an index.rst.
  16 This index file must refence your other rst files.
  17
  18 * Here is an example index.rst
  19
  20 .. code-block:: bash
  21
  22   =====================
  23   Example Documentation
  24   =====================
  25
  26   Contents:
  27
  28   .. toctree::
  29      :numbered:
  30      :maxdepth: 4
  31
  32      documentation-example.rst
  33
  34   ..
  35       Leave these at the bottom of 'index.rst' file
  36
  37   Revision: _sha1_
  38
  39   Build date: |today|
  40
  41
  42 The Sphinx Build
  43 ================
  44
  45 When you push documentation changes to gerrit a jenkins job will create html documentation.
  46
  47 * Verify Jobs
  48
  49 For verify jobs a link to the documentation will show up as a comment in gerrit for you to see the result.
  50
  51 * Merge jobs
  52
  53 Once you are happy with the look of your documentation you can submit the patchset the merge job will
  54 copy the output of each documentation directory to http://artifacts.opnfv.org/$project/docs/$name_of_your_folder/index.html
  55
  56 Here are some quick examples of how to use rst markup
  57
  58 This is a headline::
  59
  60   here is some code, note that it is indented
  61
  62 links are easy to add: Here is a link to sphinx, the tool that we are using to generate documetation http://sphinx-doc.org/
  63
  64 * Bulleted Items
  65
  66   **this will be bold**
  67
  68 .. code-block:: bash
  69
  70   echo "Heres is a code block with bash syntax highlighting"