docs/guides/onap-developer/how-to-use-docs/addendum.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License. http://creativecommons.org/licenses/by/4.0
   3
   4 Addendum
   5 ========
   6
   7 Index File
   8 ----------
   9
  10 The index file must relatively reference your other rst files in that directory.
  11
  12 Here is an example index.rst :
  13
  14 .. code-block:: bash
  15
  16     *******************
  17     Documentation Title
  18     *******************
  19
  20     .. toctree::
  21        :numbered:
  22        :maxdepth: 2
  23
  24        documentation-example
  25
  26 Source Files
  27 ------------
  28
  29 Document source files have to be written in reStructuredText format (rst).
  30 Each file would be built as an html page.
  31
  32 Here is an example source rst file :
  33
  34 .. code-block:: bash
  35
  36     =============
  37     Chapter Title
  38     =============
  39
  40     Section Title
  41     =============
  42
  43     Subsection Title
  44     ----------------
  45
  46     Hello!
  47
  48 Writing RST Markdown
  49 --------------------
  50
  51 See http://sphinx-doc.org/rest.html .
  52
  53 **Hint:**
  54 You can add html content that only appears in html output by using the
  55 'only' directive with build type
  56 ('html' and 'singlehtml') for an ONAP document. But, this is not encouraged.
  57
  58 .. code-block:: bash
  59
  60     .. only:: html
  61         This line will be shown only in html version.
  62
  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
 108 Jenkins Jobs
 109 ------------
 110
 111 Verify Job
 112 ++++++++++
 113
 114 The verify job name is **doc-{stream}-verify-rtd**
 115
 116 Proposed changes in files in any repository with top level docs folder
 117 in the repository and RST files in below this folder
 118 will be verified by this job as part of a gerrit code review.
 119
 120 .. Important::
 121    The contributing author and every reviewer on a gerrit code review
 122    should always review the Jenkins log before approving and merging a
 123    change.  The log review should include:
 124
 125    * Using a browser or other editor to search for a pattern in the
 126      *console log* that matches files in the patch set.  This will quickly
 127      identify errors and warnings that are related to the patch set and
 128      repository being changed.
 129
 130    * Using a browser to click on the *html* folder included in the log
 131      and preview how the proposed changes will look when published at
 132      Read The Docs. Small changes can be easily made in the patch set.
 133      UML and Graphviz defined diagrams do not currently
 134      render in the verify job log, but will render at Read The Docs
 135      when the change is merged.
 136
 137 Merge Job
 138 +++++++++
 139
 140 The merge job name is **doc-{stream}-merge-rtd**.
 141
 142 When a committer merges a patch that includes files matching the
 143 path described above, the doc project merge job will trigger an
 144 update at readthedocs.  There may be some delay after the merge job
 145 completes until new version appears at Read The Docs.
 146
 147 Read The Docs URLs
 148 ------------------
 149
 150 When referencing versions of documentation a Read The Docs the following
 151 URL conventions should be used
 152
 153  +----------------------------------+----------------------------------------+
 154  | URL                              | To Refer to                            |
 155  +==================================+========================================+
 156  | docs.onap.org                    | Most recent approved named release     |
 157  +----------------------------------+----------------------------------------+
 158  | docs.onap.org/en/latest          | Latest master branch all projects      |
 159  +----------------------------------+----------------------------------------+
 160  | docs.onap.org/en/*named release* | An approved name release eg. amsterdam |
 161  +----------------------------------+----------------------------------------+