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