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

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