Documentation style guide

This section describes style guide for writing the documentation. It is based on Sphinx based documentation style guide.

Filenames

Use only lowercase alphabetic characters and - (minus) symbol.

Whitespaces

Indentation

Indent with 2 spaces.

Except:

  • toctree directive requires a 3 spaces indentation.

Blank lines

One blank line before each section (e.g. H1, H2 ..). See Headings for an example.

One blank line to separate directives.

Some text before.

.. note::

  Some note.

Exception: directives can be written without blank lines if they are only one line long.

.. note:: A short note.

Line length

Limit all lines to a maximum of 145 characters.

Headings

Use the following symbols to create headings:

  1. # with overline

  2. * with overline

  3. =

  4. -

  5. ^

  6. "

As an example:

##################
H1: document title
##################

Introduction text.


*********
Sample H2
*********

Sample content.


**********
Another H2
**********

Sample H3
=========

Sample H4
---------

Sample H5
^^^^^^^^^

Sample H6
"""""""""

And some text.

If you need more than heading level 4 (i.e. H5 or H6), then you should consider creating a new document.

There should be only one H1 in a document.

Note

See also Sphinx’s documentation about sections 1.

Code blocks

Use the code-block directive and specify the programming language. As an example:

.. code-block:: python

  import this