DocumentationStyle.rst

   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
  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.
  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
  44 reST Conventions
  45 ----------------
  46
  47 Basics
  48 ~~~~~~
  49
  50 Many of the basic documentation guidelines match those of the `coding style
  51 guide <CodingStyle.rst>`__.
  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
  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
  79 ~~~~~~~~~~
  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
  90 ~~~~~~
  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
 111 ~~~~
 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
 122 ~~~~~~~~~~~
 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
 133 - Use notes sparingly. Avoid having more than one per subsection.
 134
 135 Tables
 136 ~~~~~~
 137
 138 - Use either graphic tables, list tables or CSV tables.
 139
 140 Graphic tables
 141 ++++++++++++++
 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::
 170   The ``table`` role - ``.. table:: <name>`` -  can be safely omitted.
 171
 172 List tables
 173 +++++++++++
 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
 191 ++++++++++
 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
 204 ~~~~~~~~~~~~~~~~~
 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
 249 ~~~~~~~~~~~~~~~~~~~~~~~
 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
 257 ~~~~~~~~
 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
 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
 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>`__