docs/guides/onap-developer/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 built 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
  63 Creating Indices
  64 ----------------
  65
  66 Building an index for your Sphinx project is relatively simple. First, tell Sphinx that
  67 you want it to build an index by adding something like this after your TOC tree:
  68
  69 .. code-block:: rst
  70
  71     Indices and Search
  72     ==================
  73
  74     * :ref:`genindex`
  75     * :ref:`search`
  76
  77 **Hint:**
  78 Note that search was included here. It works out of the box with any Sphinx project, so you
  79 don't need to do anything except include a reference to it in your :code:`index.rst` file.
  80
  81 Now, to generate a index entry in your RST, do one of the following:
  82
  83 .. code-block:: rst
  84
  85    Some content that requires an :index:`index`.
  86
  87 or
  88
  89 .. code-block:: rst
  90
  91     .. index::
  92         single: myterm
  93
  94     Some header containing myterm
  95     =============================
  96
  97 In the second case, Sphinx will create a link in the index to the paragraph that follows
  98 the index entry declaration.
  99
 100 When your project is built, Sphinx will generate an index page populated with the entries
 101 you created in the source RST.
 102
 103 These are simple cases with simple options. For more information about indexing with Sphinx,
 104 please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_.
 105
 106
 107 Jenkins Jobs
 108 ------------
 109
 110 Verify Job
 111 ++++++++++
 112
 113 The verify job name is **doc-{stream}-verify-rtd**
 114
 115 Proposed changes in files in any repository with the path
 116
 117 .. bash
 118
 119          docs/**/*.rst
 120
 121 will be verified by this job prior to a gerrit code review.
 122 Please check the Jenkins log carefully for warnings.
 123 You can improve your document even if the verify job succeeded.
 124
 125 Merge Job
 126 +++++++++
 127
 128 The merge job name is **doc-{stream}-merge-rtd**.
 129
 130 When a committer merges a patch that includes files matching the path described above,
 131 the doc project merge job will trigger an update at readthedocs.
 132 This might take about 15 minutes while readthedocs
 133 builds the documentation.