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:

# with overline
* with overline
=
-
^
"

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

Code blocks

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

.. code-block:: python

  import this

Links and references

Use links and references footnotes with the target-notes directive. As an example:

#############
Some document
#############

Some text which includes links to `Example website`_ and many other links.

`Example website`_ can be referenced multiple times.

(... document content...)

And at the end of the document...

**********
References
**********

.. target-notes::

.. _`Example website`: http://www.example.com/