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     ./yourfolder_name1/file_name1.rst
  11     ./yourfolder_nameN/file_nameX.rst
  12     ./documentation-example.rst
  13     ./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   Example Documentation table of contents
  23   =======================================
  24
  25   Contents:
  26
  27   .. toctree::
  28      :numbered:
  29      :maxdepth: 4
  30
  31      documentation-example.rst
  32
  33   Indices and tables
  34   ==================
  35
  36   * :ref:`search`
  37
  38   Revision: _sha1_
  39
  40   Build date: |today|
  41
  42
  43 The Sphinx Build
  44 ================
  45
  46 When you push documentation changes to gerrit a jenkins job will create html documentation.
  47
  48 * Verify Jobs
  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 copy the output of each documentation directory to http://artifacts.opnfv.org/$project/docs/$name_of_your_folder/index.html
  54
  55 Here are some quick examples of how to use rst markup
  56
  57 This is a headline::
  58
  59   here is some code, note that it is indented
  60
  61 links are easy to add: Here is a link to sphinx, the tool that we are using to generate documetation http://sphinx-doc.org/
  62
  63 * Bulleted Items
  64
  65   **this will be bold**
  66
  67 .. code-block:: bash
  68
  69   echo "Heres is a code block with bash syntax highlighting"
  70
  71
  72 Leave these at the bottom of each of your documents they are used internally
  73
  74 Revision: _sha1_
  75
  76 Build date: |today|