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