blob: 160b18fde5d82320d6a4c7e5d2497b2459c655d7 [file] [log] [blame]
Rich Bennettac93e0e2017-07-19 01:36:52 -04001.. This work is licensed under a Creative Commons Attribution 4.0 International License.
2
3Addendum
4========
5
6Index File
Rich Bennett976bffd2017-08-15 07:56:32 -04007----------
Rich Bennettac93e0e2017-07-19 01:36:52 -04008
9The index file must relatively reference your other rst files in that directory.
10
11Here 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
25Source Files
Rich Bennett976bffd2017-08-15 07:56:32 -040026------------
Rich Bennettac93e0e2017-07-19 01:36:52 -040027
28Document source files have to be written in reStructuredText format (rst).
Rich Bennett5baea462017-09-13 03:19:19 -040029Each file would be built as an html page.
Rich Bennettac93e0e2017-07-19 01:36:52 -040030
31Here 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
47Writing RST Markdown
Rich Bennett976bffd2017-08-15 07:56:32 -040048--------------------
Rich Bennettac93e0e2017-07-19 01:36:52 -040049
50See http://sphinx-doc.org/rest.html .
51
52**Hint:**
53You 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
Rich Bennett5baea462017-09-13 03:19:19 -040062
Spencer Seidela10d3f52017-09-07 13:58:17 -040063.. index:: single: indices
64
65Creating Indices
66----------------
67
68Building an index for your Sphinx project is relatively simple. First, tell Sphinx that
69you 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:**
80Note that search was included here. It works out of the box with any Sphinx project, so you
81don't need to do anything except include a reference to it in your :code:`index.rst` file.
82
83Now, 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
89or
90
91.. code-block:: rst
92
93 .. index::
94 single: myterm
95
96 Some header containing myterm
97 =============================
98
99In the second case, Sphinx will create a link in the index to the paragraph that follows
100the index entry declaration.
101
102When your project is built, Sphinx will generate an index page populated with the entries
103you created in the source RST.
104
105These are simple cases with simple options. For more information about indexing with Sphinx,
106please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_.
107
Rich Bennett5baea462017-09-13 03:19:19 -0400108
Rich Bennett976bffd2017-08-15 07:56:32 -0400109Jenkins Jobs
110------------
111
Rich Bennettac93e0e2017-07-19 01:36:52 -0400112Verify Job
Rich Bennett976bffd2017-08-15 07:56:32 -0400113++++++++++
Rich Bennettac93e0e2017-07-19 01:36:52 -0400114
Rich Bennett976bffd2017-08-15 07:56:32 -0400115The verify job name is **doc-{stream}-verify-rtd**
Rich Bennettac93e0e2017-07-19 01:36:52 -0400116
Rich Bennett5baea462017-09-13 03:19:19 -0400117Proposed changes in files in any repository with the path
118.. bash
119 docs/**/*.rst
120
121will be verified by this job prior to a gerrit code review.
Rich Bennett976bffd2017-08-15 07:56:32 -0400122Please check the Jenkins log carefully for warnings.
123You can improve your document even if the verify job succeeded.
Rich Bennettac93e0e2017-07-19 01:36:52 -0400124
125Merge Job
Rich Bennett976bffd2017-08-15 07:56:32 -0400126+++++++++
Rich Bennettac93e0e2017-07-19 01:36:52 -0400127
Rich Bennett976bffd2017-08-15 07:56:32 -0400128The merge job name is **doc-{stream}-merge-rtd**.
Rich Bennettac93e0e2017-07-19 01:36:52 -0400129
Rich Bennett5baea462017-09-13 03:19:19 -0400130When a committer merges a patch that includes files matching the path described above,
131the doc project merge job will trigger an update at readthedocs.
132This might take about 15 minutes while readthedocs
133builds the documentation.