]>
Commit | Line | Data |
---|---|---|
ccaac768 SF |
1 | .. |
2 | Copyright (c) 2016 Stephen Finucane <stephen@that.guru> | |
3 | ||
4 | Licensed under the Apache License, Version 2.0 (the "License"); you may | |
5 | not use this file except in compliance with the License. You may obtain | |
6 | a copy of the License at | |
7 | ||
8 | http://www.apache.org/licenses/LICENSE-2.0 | |
9 | ||
10 | Unless required by applicable law or agreed to in writing, software | |
11 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |
12 | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |
13 | License for the specific language governing permissions and limitations | |
14 | under the License. | |
15 | ||
16 | Convention for heading levels in Open vSwitch documentation: | |
17 | ||
18 | ======= Heading 0 (reserved for the title in a document) | |
19 | ------- Heading 1 | |
20 | ~~~~~~~ Heading 2 | |
21 | +++++++ Heading 3 | |
22 | ''''''' Heading 4 | |
23 | ||
24 | Avoid deeper levels because they do not render well. | |
25 | ||
26 | ================================ | |
27 | Open vSwitch Documentation Style | |
28 | ================================ | |
29 | ||
30 | This file describes the documentation style used in all documentation found in | |
9f13fbef SF |
31 | Open vSwitch. Documentation includes any documents found in ``Documentation`` |
32 | along with any ``README``, ``INSTALL``, or generally ``rst`` suffixed documents | |
33 | found in the project tree. | |
ccaac768 SF |
34 | |
35 | reStructuredText vs. Sphinx | |
36 | --------------------------- | |
37 | ||
38 | reStructuredText (reST) is the syntax, while Sphinx is a documentation | |
39 | generator. Sphinx introduces a number of extensions to reST, like the | |
40 | ``:ref:`` role, which can and should be used in documentation, but these will | |
41 | not work correctly on GitHub. As such, these extensions should not be used in | |
42 | any documentation in the root level, such as the ``README``. | |
43 | ||
26ea2d40 SF |
44 | reST Conventions |
45 | ---------------- | |
46 | ||
ccaac768 | 47 | Basics |
26ea2d40 | 48 | ~~~~~~ |
ccaac768 SF |
49 | |
50 | Many of the basic documentation guidelines match those of the `coding style | |
60230e06 | 51 | guide <CodingStyle.rst>`__. |
ccaac768 SF |
52 | |
53 | - Use reStructuredText (reST) for all documentation. | |
54 | ||
55 | Sphinx extensions can be used, but only for documentation in the | |
56 | ``Documentation`` folder. | |
57 | ||
ccaac768 SF |
58 | - Limit lines at 79 characters. |
59 | ||
60 | .. note:: | |
61 | An exception to this rule is text within code-block elements that cannot be | |
62 | wrapped and links within references. | |
63 | ||
64 | - Use spaces for indenation. | |
65 | ||
66 | - Match indentation levels. | |
67 | ||
68 | A change in indentation level usually signifies a change in content nesting, | |
69 | by either closing the existing level or introducing a new level. | |
70 | ||
71 | - Avoid trailing spaces on lines. | |
72 | ||
73 | - Include a license (see this file) in all docs. | |
74 | ||
75 | - Most importantly, always build and display documentation before submitting | |
76 | changes! Docs aren't unit testable, so visible inspection is necessary. | |
77 | ||
78 | File Names | |
26ea2d40 | 79 | ~~~~~~~~~~ |
ccaac768 SF |
80 | |
81 | - Use hyphens as space delimiters. For example: ``my-readme-document.rst`` | |
82 | ||
83 | - Use lowercase filenames. | |
84 | ||
85 | .. note:: | |
86 | An exception to this rule is any documents found in the root-level of the | |
87 | project. | |
88 | ||
89 | Titles | |
26ea2d40 | 90 | ~~~~~~ |
ccaac768 SF |
91 | |
92 | - Use the following headers levels. | |
93 | ||
94 | | ======= Heading 0 (reserved for the title in a document) | |
95 | | ------- Heading 1 | |
96 | | ~~~~~~~ Heading 2 | |
97 | | +++++++ Heading 3 | |
98 | | ''''''' Heading 4 | |
99 | ||
100 | .. note:: | |
101 | ||
102 | Avoid using lower heading levels by rewriting and reorganizing the | |
103 | information. | |
104 | ||
105 | - Under- and overlines should be of the same length as that of the heading | |
106 | text. | |
107 | ||
108 | - Use "title case" for headers. | |
109 | ||
110 | Code | |
26ea2d40 | 111 | ~~~~ |
ccaac768 SF |
112 | |
113 | - Use ``::``, the ``code`` role or the ``code-block:: <syntax>`` role to prefix | |
114 | code. | |
115 | ||
116 | - Prefix commands with ``$``. | |
117 | ||
118 | - Where possible, include fully-working snippets of code. If there | |
119 | pre-requisites, explain what they are and how to achieve them. | |
120 | ||
121 | Admonitions | |
26ea2d40 | 122 | ~~~~~~~~~~~ |
ccaac768 SF |
123 | |
124 | - Use admonitions to call attention to important information.:: | |
125 | ||
126 | .. note:: | |
127 | ||
128 | This is a sample callout for some useful tip or trick. | |
129 | ||
130 | Example admonitions include: ``warning``, ``important``, ``note``, ``tip`` or | |
131 | ``seealso``. | |
132 | ||
26ea2d40 SF |
133 | - Use notes sparingly. Avoid having more than one per subsection. |
134 | ||
ccaac768 | 135 | Tables |
26ea2d40 | 136 | ~~~~~~ |
ccaac768 SF |
137 | |
138 | - Use either graphic tables, list tables or CSV tables. | |
139 | ||
140 | Graphic tables | |
26ea2d40 | 141 | ++++++++++++++ |
ccaac768 SF |
142 | |
143 | :: | |
144 | ||
145 | .. table:: OVS-Linux kernel compatibility | |
146 | ||
147 | ============ ============== | |
148 | Open vSwitch Linux kernel | |
149 | ============ ============== | |
150 | 1.4.x 2.6.18 to 3.2 | |
151 | 1.5.x 2.6.18 to 3.2 | |
152 | 1.6.x 2.6.18 to 3.2 | |
153 | ============ ============== | |
154 | ||
155 | :: | |
156 | ||
157 | .. table:: OVS-Linux kernel compatibility | |
158 | ||
159 | +--------------+---------------+ | |
160 | | Open vSwitch | Linux kernel | | |
161 | +==============+===============+ | |
162 | | 1.4.x | 2.6.18 to 3.2 | | |
163 | +--------------+---------------+ | |
164 | | 1.5.x | 2.6.18 to 3.2 | | |
165 | +--------------+---------------+ | |
166 | | 1.6.x | 2.6.18 to 3.2 | | |
167 | +--------------+---------------+ | |
168 | ||
169 | .. note:: | |
9f13fbef | 170 | The ``table`` role - ``.. table:: <name>`` - can be safely omitted. |
ccaac768 SF |
171 | |
172 | List tables | |
26ea2d40 | 173 | +++++++++++ |
ccaac768 SF |
174 | |
175 | :: | |
176 | ||
177 | .. list-table:: OVS-Linux kernel compatibility | |
178 | :widths: 10 15 | |
179 | :header-rows: 1 | |
180 | ||
181 | * - Open vSwitch | |
182 | - Linux kernel | |
183 | * - 1.4.x | |
184 | - 2.6.18 to 3.2 | |
185 | * - 1.5.x | |
186 | - 2.6.18 to 3.2 | |
187 | * - 1.6.x | |
188 | - 2.6.18 to 3.2 | |
189 | ||
190 | CSV tables | |
26ea2d40 | 191 | ++++++++++ |
ccaac768 SF |
192 | |
193 | :: | |
194 | ||
195 | .. csv-table:: OVS-Linux kernel compatibility | |
196 | :header: Open vSwitch, Linux kernel | |
197 | :widths: 10 15 | |
198 | ||
199 | 1.4.x, 2.6.18 to 3.2 | |
200 | 1.5.x, 2.6.18 to 3.2 | |
201 | 1.6.x, 2.6.18 to 3.2 | |
202 | ||
203 | Cross-referencing | |
26ea2d40 | 204 | ~~~~~~~~~~~~~~~~~ |
ccaac768 SF |
205 | |
206 | - To link to an external file or document, include as a link.:: | |
207 | ||
208 | Here's a `link <http://openvswitch.org>`__ to the Open vSwitch website. | |
209 | ||
210 | ||
211 | Here's a `link`_ in reference style. | |
212 | ||
213 | .. _link: http://openvswitch.org | |
214 | ||
215 | - You can also use citations.:: | |
216 | ||
217 | Refer to the Open vSwitch documentation [1]_. | |
218 | ||
219 | References | |
220 | ---------- | |
221 | ||
222 | .. [1]: http://openvswitch.org | |
223 | ||
224 | - To cross-reference another doc, use the ``doc`` role.:: | |
225 | ||
226 | Here is a link to the :doc:`/README.rst` | |
227 | ||
228 | .. note:: | |
229 | This is a Sphinx extension. Do not use this in any top-level documents. | |
230 | ||
231 | - To cross-reference an arbitrary location in a doc, use the ``ref`` role.:: | |
232 | ||
233 | .. _sample-crossref | |
234 | ||
235 | Title | |
236 | ~~~~~ | |
237 | ||
238 | Hello, world. | |
239 | ||
240 | Another Title | |
241 | ~~~~~~~~~~~~~ | |
242 | ||
243 | Here is a cross-reference to :ref:`sample-crossref`. | |
244 | ||
245 | .. note:: | |
246 | This is a Sphinx extension. Do not use this in any top-level documents. | |
247 | ||
248 | Figures and Other Media | |
26ea2d40 | 249 | ~~~~~~~~~~~~~~~~~~~~~~~ |
ccaac768 SF |
250 | |
251 | - All images should be in ASCII format and included in code-blocks to preserve | |
252 | formatting. | |
253 | ||
254 | - Include other reStructuredText verbatim in a current document | |
255 | ||
256 | Comments | |
26ea2d40 | 257 | ~~~~~~~~ |
ccaac768 SF |
258 | |
259 | - Comments are indicated by means of the ``..`` marker.:: | |
260 | ||
261 | .. TODO(stephenfin) This section needs some work. This TODO will not | |
262 | appear in the final generated document, however. | |
263 | ||
26ea2d40 SF |
264 | Writing Style |
265 | ------------- | |
266 | ||
267 | Follow these guidelines to ensure readability and consistency of the Open | |
268 | vSwitch documentation. These guidelines are based on the `IBM Style Guide | |
269 | <http://www.redbooks.ibm.com/Redbooks.nsf/ibmpressisbn/9780132101301?Open>`__. | |
270 | ||
271 | - Use standard US English | |
272 | ||
273 | Use a spelling and grammar checking tool as necessary. | |
274 | ||
275 | - Expand initialisms and acronyms on first usage. | |
276 | ||
277 | Commonly used terms like CPU or RAM are allowed. | |
278 | ||
279 | .. list-table:: Example | |
280 | :header-rows: 1 | |
281 | ||
282 | * - Do not use | |
283 | - Do use | |
284 | * - OVS is a virtual switch. OVS has... | |
285 | - Open vSwitch (OVS) is a virtual switch. OVS has... | |
286 | * - The VTEP emulator is... | |
287 | - The Virtual Tunnel Endpoint (VTEP) emulator is... | |
288 | ||
289 | - Write in the active voice | |
290 | ||
291 | The subject should do the verb's action, rather than be acted upon. | |
292 | ||
293 | .. list-table:: Example | |
294 | :header-rows: 1 | |
295 | ||
296 | * - Do not use | |
297 | - Do use | |
298 | * - A bridge is created by you | |
299 | - Create a bridge | |
300 | ||
301 | - Write in the present tense | |
302 | ||
303 | .. list-table:: Example | |
304 | :header-rows: 1 | |
305 | ||
306 | * - Do not use | |
307 | - Do use | |
308 | * - Once the bridge is created, you can create a port | |
309 | - Once the bridge is created, create a port | |
310 | ||
311 | - Write in second person | |
312 | ||
313 | .. list-table:: Example | |
314 | :header-rows: 1 | |
315 | ||
316 | * - Do not use | |
317 | - Do use | |
318 | * - To create a bridge, the user runs: | |
319 | - To create a bridge, run: | |
320 | ||
321 | - Keep sentences short and consise | |
322 | ||
323 | - Eliminate needless politeness | |
324 | ||
325 | Avoid "please" and "thank you" | |
326 | ||
ccaac768 SF |
327 | Useful Links |
328 | ------------ | |
329 | ||
330 | * `Quick reStructuredText | |
331 | <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__ | |
332 | * `Sphinx Documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`__ |