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 .. index:: single: indices
  64
  65 Creating Indices
  66 ----------------
  67
  68 Building an index for your Sphinx project is relatively simple. First, tell Sphinx that
  69 you want it to build an index by adding something like this after your TOC tree:
  70
  71 .. code-block:: rst
  72
  73     Indices and Search
  74     ==================
  75
  76     * :ref:`genindex`
  77     * :ref:`search`
  78
  79 **Hint:**
  80 Note that search was included here. It works out of the box with any Sphinx project, so you
  81 don't need to do anything except include a reference to it in your :code:`index.rst` file.
  82
  83 Now, to generate a index entry in your RST, do one of the following:
  84
  85 .. code-block:: rst
  86
  87    Some content that requires an :index:`index`.
  88
  89 or
  90
  91 .. code-block:: rst
  92
  93     .. index::
  94         single: myterm
  95
  96     Some header containing myterm
  97     =============================
  98
  99 In the second case, Sphinx will create a link in the index to the paragraph that follows
 100 the index entry declaration.
 101
 102 When your project is built, Sphinx will generate an index page populated with the entries
 103 you created in the source RST.
 104
 105 These are simple cases with simple options. For more information about indexing with Sphinx,
 106 please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_.
 107
 108
 109 Jenkins Jobs
 110 ------------
 111
 112 Verify Job
 113 ++++++++++
 114
 115 The verify job name is **doc-{stream}-verify-rtd**
 116
 117 Proposed changes in files in any repository with the path
 118 .. bash
 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.