docs/how-to-use-docs/addendum.rst

   1 ========
   2 Addendum
   3 ========
   4
   5 Index File
   6 ==========
   7
   8 The index file must relatively refence your other rst files in that directory.
   9
  10 Here is an example index.rst :
  11
  12 .. code-block:: bash
  13
  14     *******************
  15     Documentation Title
  16     *******************
  17
  18     .. toctree::
  19        :numbered:
  20        :maxdepth: 2
  21
  22        documentation-example
  23
  24 Source Files
  25 ============
  26
  27 Document source files have to be written in reStructuredText format (rst).
  28 Each file would be build as an html page.
  29
  30 Here is an example source rst file :
  31
  32 .. code-block:: bash
  33
  34     =============
  35     Chapter Title
  36     =============
  37
  38     Section Title
  39     =============
  40
  41     Subsection Title
  42     ----------------
  43
  44     Hello!
  45
  46 Writing RST Markdown
  47 ====================
  48
  49 See http://sphinx-doc.org/rest.html .
  50
  51 **Hint:**
  52 You can add dedicated contents by using 'only' directive with build type
  53 ('html' and 'singlehtml') for OPNFV document. But, this is not encouraged to
  54 use since this may make different views.
  55
  56 .. code-block:: bash
  57
  58     .. only:: html
  59         This line will be shown only in html version.
  60
  61 Verify Job
  62 ----------
  63
  64 The verify job name is **docs-verify-rtd-{branch}**.
  65
  66 When you send document changes to gerrit, jenkins will create your documents
  67 in HTML formats (normal and single-page) to verify that new document can be
  68 built successfully. Please check the jenkins log and artifact carefully.
  69 You can improve your document even though if the build job succeeded.
  70
  71 Merge Job
  72 ----------
  73
  74 The merge job name is **docs-merge-rtd-{branch}**.
  75
  76 Once the patch is merged, jenkins will automatically trigger building of
  77 the new documentation. This might take about 15 minutes while readthedocs
  78 builds the documentatation. The newly built documentation shall show up
  79 as appropriate placed in docs.opnfv.org/{branch}/path-to-file.