1 .. This work is licensed under a Creative Commons Attribution 4.0
2 .. International License. http://creativecommons.org/licenses/by/4.0
10 The index file must relatively reference your other rst files in that directory.
12 Here is an example index.rst :
29 Document source files have to be written in reStructuredText format (rst).
30 Each file would be built as an html page.
32 Here is an example source rst file :
51 See http://sphinx-doc.org/rest.html .
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.
61 This line will be shown only in html version.
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:
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.
82 Now, to generate a index entry in your RST, do one of the following:
86 Some content that requires an :index:`index`.
95 Some header containing myterm
96 =============================
98 In the second case, Sphinx will create a link in the index to the paragraph that follows
99 the index entry declaration.
101 When your project is built, Sphinx will generate an index page populated with the entries
102 you created in the source RST.
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>`_.
114 The verify job name is **doc-{stream}-verify-rtd**
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.
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:
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.
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.
137 The merge job name is **doc-{stream}-merge-rtd**.
139 When a committer merges a patch that includes files matching the
140 path described above, the doc project merge job will trigger an
141 update at readthedocs. There may be some delay after the merge job
142 completes until new version appears at Read The Docs.
147 When referencing versions of documentation a Read The Docs the following
148 URL conventions should be used
150 +----------------------------------+----------------------------------------+
151 | URL | To Refer to |
152 +==================================+========================================+
153 | docs.onap.org | Most recent approved named release |
154 +----------------------------------+----------------------------------------+
155 | docs.onap.org/en/latest | Latest master branch all projects |
156 +----------------------------------+----------------------------------------+
157 | docs.onap.org/en/*named release* | An approved name release eg. amsterdam |
158 +----------------------------------+----------------------------------------+