Docs Style Guide

Abstract

This document focuses on style-guide. It is a kind of coding standards applied to documentation files. It is not about documentation content.

RestructuredText With Sphinx Directives

This documentation uses Sphinx, which itself uses reStructuredText syntax.

Filenames

Use lowercase alphanumeric characters and - (minus) symbol.

Suffix filenames with the .rst extension.

Whitespaces

Indent with 3 spaces.

Blank Lines

Two blank lines before overlined sections, i.e. before H1 and H2. One blank line before other sections.

One blank line to separate directives.

Some text before.

.. note::

  Some note.

Line Length

Limit all lines to a maximum of 130 characters.

Headings

Use the following symbols to create headings:

  1. # with overline
  2. =
  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.

Code Blocks

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

.. code-block:: python

  import this

Quality Assurance

We use Rakpart to run QA checks against our docs.

Checks are included in the main Makefile as targets.

Run make help for more info !