OVN Documentation Style

This file describes the documentation style used in all documentation found in OVN. Documentation includes any documents found in Documentation along with any README, MAINTAINERS, or generally rst suffixed documents found in the project tree.

reStructuredText vs. Sphinx

reStructuredText (rST) is the syntax, while Sphinx is a documentation generator. Sphinx introduces a number of extensions to rST, like the :ref: role, which can and should be used in documentation, but these will not work correctly on GitHub. As such, these extensions should not be used in any documentation in the root level, such as the README.

rST Conventions

Basics

Many of the basic documentation guidelines match those of the OVN Coding Style.

Use reStructuredText (rST) for all documentation.

Sphinx extensions can be used, but only for documentation in the Documentation folder.
Limit lines at 79 characters.

Note

An exception to this rule is text within code-block elements that cannot be wrapped and links within references.
Use spaces for indentation.
Match indentation levels.

A change in indentation level usually signifies a change in content nesting, by either closing the existing level or introducing a new level.
Avoid trailing spaces on lines.
Include a license (see this file) in all docs.
Most importantly, always build and display documentation before submitting changes! Docs aren’t unit testable, so visible inspection is necessary.

File Names

Use hyphens as space delimiters. For example: my-readme-document.rst

Note

An exception to this rule is any man pages, which take an trailing number corresponding to the number of arguments required. This number is preceded by an underscore.
Use lowercase filenames.

Note

An exception to this rule is any documents found in the root-level of the project.

Titles

Use the following headers levels.

======= Heading 0 (reserved for the title in a document)

------- Heading 1

~~~~~~~ Heading 2

+++++++ Heading 3

''''''' Heading 4

Note

Avoid using lower heading levels by rewriting and reorganizing the information.
Under- and overlines should be of the same length as that of the heading text.
Use “title case” for headers.

Code

Use :: to prefix code.
Don’t use syntax highlighting such as .. highlight:: <syntax> or code-block:: <syntax> because it depends on external pygments library.
Prefix commands with $.
Where possible, include fully-working snippets of code. If there pre-requisites, explain what they are and how to achieve them.

Admonitions

Use admonitions to call attention to important information.:
```
.. note::

   This is a sample callout for some useful tip or trick.
```
Example admonitions include: warning, important, note, tip or seealso.
Use notes sparingly. Avoid having more than one per subsection.

Tables

Use either graphic tables, list tables or CSV tables.

Graphic tables

.. table:: OVS-Linux kernel compatibility

  ============ ==============
  Open vSwitch Linux kernel
  ============ ==============
  1.4.x        2.6.18 to 3.2
  1.5.x        2.6.18 to 3.2
  1.6.x        2.6.18 to 3.2
  ============ ==============

.. table:: OVS-Linux kernel compatibility

  +--------------+---------------+
  | Open vSwitch | Linux kernel  |
  +==============+===============+
  | 1.4.x        | 2.6.18 to 3.2 |
  +--------------+---------------+
  | 1.5.x        | 2.6.18 to 3.2 |
  +--------------+---------------+
  | 1.6.x        | 2.6.18 to 3.2 |
  +--------------+---------------+

Note

The table role - .. table:: <name> - can be safely omitted.

List tables

.. list-table:: OVS-Linux kernel compatibility
   :widths: 10 15
   :header-rows: 1

   * - Open vSwitch
     - Linux kernel
   * - 1.4.x
     - 2.6.18 to 3.2
   * - 1.5.x
     - 2.6.18 to 3.2
   * - 1.6.x
     - 2.6.18 to 3.2

CSV tables

.. csv-table:: OVS-Linux kernel compatibility
   :header: Open vSwitch, Linux kernel
   :widths: 10 15

   1.4.x, 2.6.18 to 3.2
   1.5.x, 2.6.18 to 3.2
   1.6.x, 2.6.18 to 3.2

Cross-referencing

To link to an external file or document, include as a link.:

Here's a `link <http://openvswitch.org>`__ to the Open vSwitch website.

Here's a `link`_ in reference style.

.. _link: http://openvswitch.org

You can also use citations.:

Refer to the Open vSwitch documentation [1]_.

References
----------

.. [1]: http://openvswitch.org

To cross-reference another doc, use the doc role.:
```
Here is a link to the :doc:`/README.rst`
```
Note

This is a Sphinx extension. Do not use this in any top-level documents.
To cross-reference an arbitrary location in a doc, use the ref role.:
```
.. _sample-crossref

Title
~~~~~

Hello, world.

Another Title
~~~~~~~~~~~~~

Here is a cross-reference to :ref:`sample-crossref`.
```
Note

This is a Sphinx extension. Do not use this in any top-level documents.

Figures and Other Media

All images should be in PNG format and compressed where possible. For PNG files, use OptiPNG and AdvanceCOMP’s advpng:
```
$ optipng -o7 -zm1-9 -i0 -strip all <path_to_png>
$ advpng -z4 <path_to_png>
```
Any ASCII text “images” should be included in code-blocks to preserve formatting
Include other reStructuredText verbatim in a current document

Comments

Comments are indicated by means of the .. marker.:

.. TODO(stephenfin) This section needs some work. This TODO will not
   appear in the final generated document, however.

Man Pages

In addition to the above, man pages have some specific requirements:

You must define the following sections:
- Synopsis
- Description
- Options
Note that NAME is not included - this is automatically generated by Sphinx and should not be manually defined. Also note that these do not need to be uppercase - Sphinx will do this automatically.

Additional sections are allowed. Refer to man-pages(8) for information on the sections generally allowed.
You must not define a NAME section.

See above.
The OPTIONS section must describe arguments and options using the program and option directives.

This ensures the output is formatted correctly and that you can cross-reference various programs and commands from the documentation. For example:
```
.. program:: ovs-do-something

.. option:: -f, --force

    Force the operation

.. option:: -b <bridge>, --bridge <bridge>

    Name or ID of bridge
```
Important

Option argument names should be enclosed in angle brackets, as above.
Any references to the application or any other OVN application must be marked up using the program role.

This allows for easy linking in the HTML output and correct formatting in the man page output. For example:
```
To do something, run :program:`ovs-do-something`.
```
The man page must be included in the list of man page documents found in conf.py

Refer to existing man pages, such as ovn-sim for a worked example.

Writing Style

Follow these guidelines to ensure readability and consistency of the Open vSwitch documentation. These guidelines are based on the /*IBM Style Guide/*.

Use standard US English

Use a spelling and grammar checking tool as necessary.
Expand initialisms and acronyms on first usage.

Commonly used terms like CPU or RAM are allowed.

Do not use

Do use

OVS is a virtual switch. OVS has…

Open vSwitch (OVS) is a virtual switch. OVS has…

The VTEP emulator is…

The Virtual Tunnel Endpoint (VTEP) emulator is…
Write in the active voice

The subject should do the verb’s action, rather than be acted upon.

Do not use

Do use

A bridge is created by you

Create a bridge
Write in the present tense

Do not use

Do use

Once the bridge is created, you can create a port

Once the bridge is created, create a port
Write in second person

Do not use

Do use

To create a bridge, the user runs:

To create a bridge, run:
Keep sentences short and concise
Eliminate needless politeness

Avoid “please” and “thank you”

Helpful Tools

There are a number of tools, online and offline, which can be used to preview documents are you edit them:

rst.ninjs.org

An online rST editor/previewer
ReText

A simple but powerful editor for Markdown and reStructuredText. ReText is written in Python.
restview

A viewer for ReStructuredText documents that renders them on the fly.

Do not use	Do use
OVS is a virtual switch. OVS has…	Open vSwitch (OVS) is a virtual switch. OVS has…
The VTEP emulator is…	The Virtual Tunnel Endpoint (VTEP) emulator is…