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

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