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