blob: d51a41df33d57d7abd96c4d55e4d051c9046bfbf (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
.. This work is licensed under a Creative Commons Attribution 4.0
.. International License. http://creativecommons.org/licenses/by/4.0
Addendum
========
Index File
----------
The index file must relatively reference your other rst files in that directory.
Here is an example index.rst :
.. code-block:: bash
*******************
Documentation Title
*******************
.. toctree::
:numbered:
:maxdepth: 2
documentation-example
Source Files
------------
Document source files have to be written in reStructuredText format (rst).
Each file would be built as an html page.
Here is an example source rst file :
.. code-block:: bash
=============
Chapter Title
=============
Section Title
=============
Subsection Title
----------------
Hello!
Writing RST Markdown
--------------------
See http://sphinx-doc.org/rest.html .
**Hint:**
You can add html content that only appears in html output by using the
'only' directive with build type
('html' and 'singlehtml') for an ONAP document. But, this is not encouraged.
.. code-block:: bash
.. only:: html
This line will be shown only in html version.
Creating Indices
----------------
Building an index for your Sphinx project is relatively simple. First, tell Sphinx that
you want it to build an index by adding something like this after your TOC tree:
.. code-block:: rst
Indices and Search
==================
* :ref:`genindex`
* :ref:`search`
**Hint:**
Note that search was included here. It works out of the box with any Sphinx project, so you
don't need to do anything except include a reference to it in your :code:`index.rst` file.
Now, to generate a index entry in your RST, do one of the following:
.. code-block:: rst
Some content that requires an :index:`index`.
or
.. code-block:: rst
.. index::
single: myterm
Some header containing myterm
=============================
In the second case, Sphinx will create a link in the index to the paragraph that follows
the index entry declaration.
When your project is built, Sphinx will generate an index page populated with the entries
you created in the source RST.
These are simple cases with simple options. For more information about indexing with Sphinx,
please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_.
Jenkins Jobs
------------
Verify Job
++++++++++
The verify job name is **doc-{stream}-verify-rtd**
Proposed changes in files in any repository with top level docs folder
in the repository and RST files in below this folder
will be verified by this job as part of a gerrit code review.
.. Important::
The contributing author and every reviewer on a gerrit code review
should always review the Jenkins log before approving and merging a
change. The log review should include:
* Using a browser or other editor to search for a pattern in the
*console log* that matches files in the patch set. This will quickly
identify errors and warnings that are related to the patch set and
repository being changed.
* Using a browser to click on the *html* folder included in the log
and preview how the proposed changes will look when published at
Read The Docs. Small changes can be easily made in the patch set.
UML and Graphviz defined diagrams do not currently
render in the verify job log, but will render at Read The Docs
when the change is merged.
Merge Job
+++++++++
The merge job name is **doc-{stream}-merge-rtd**.
When a committer merges a patch that includes files matching the
path described above, the doc project merge job will trigger an
update at readthedocs. There may be some delay after the merge job
completes until new version appears at Read The Docs.
Read The Docs URLs
------------------
When referencing versions of documentation a Read The Docs the following
URL conventions should be used
+----------------------------------+----------------------------------------+
| URL | To Refer to |
+==================================+========================================+
| docs.onap.org | Most recent approved named release |
+----------------------------------+----------------------------------------+
| docs.onap.org/en/latest | Latest master branch all projects |
+----------------------------------+----------------------------------------+
| docs.onap.org/en/*named release* | An approved name release eg. amsterdam |
+----------------------------------+----------------------------------------+
|
