Style guide

This style guide describes the conventions that are followed by our documentation project. If you follow them, your documents will pass the doc8 tests and compile cleanly.

This documentation uses Python-sphinx, which itself uses reStructuredText syntax.

Filenames

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

Suffix filenames with the .rst extension.

Do not add ‘example’ or ‘service’ to titles of pages as these should be self evident.

Text style

Bold

We use bold text when we are referring to something important or when we are directly talking about an element of a service that we want to direct the user to. To make some text bold, you need to put the text between two sets of asterisks without any spaces between the starting and ending letter of your word: ** text you want to be bold **

Example: “You will find this under the Container Infra section of the dashboard” OR “Remember DO NOT delete this file until after…”

Highlighting

We use this when we are referring to a specific command piece of code that we are talking about, but we do not want to use a code-block for. To use this you need to place the string between two sets of tilde `` text to be highlighted ``

Example: ” Now you should have your token sourced…”

Whitespaces

Indentation

Indent with 2 spaces.

Except:

  • toctree directive requires a 3 space indentation.

Blank lines

Two blank lines before over lined sections, i.e. before H1 and H2. One blank line before other sections. 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 79 characters.

Headings

Use the following symbols to create headings:

  1. H1: # with over line

  2. H2: * with over line

  3. H3: =

  4. H4: -

  5. H5: ^

  6. H6: "

As an example:

##############
Document title
##############

Introduction text. Note the empty line after the heading.


***********
Heading two
***********

Sample content. Note two empty lines before a heading two.


*******************
Another heading two
*******************

Note how headings only have the first letter capitalised.

Sample heading three
====================

Note how from heading three onward we only have one empty line between
headings.

Sample heading four
-------------------

Sample heading five
^^^^^^^^^^^^^^^^^^^

Sample heading six
""""""""""""""""""

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.

Code blocks

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

.. code-block:: python

  import this

When documenting command line interactions code-block console should be used:

.. code-block:: console

  $ ls -la

When documenting bash or shell scripts bash or sh should be used.

Admonitions

Note

Notes can be used to emphasise a point that requires more attention.

.. note:: A short note (fits one line).

.. note::

  A long note that can span across multiple lines.

Warning

Warnings can be used to highlight things that must be done with caution.

.. warning:: A short warning (fits one line).

.. warning::

  A long warning that can span across multiple lines.

See also

See also can be used to refer to other documents.

.. seealso:: A short reference (fits one line).

.. seealso::

  A long reference that can span across multiple lines.

Tables

Tables should use the grid notation.

Header row, column 1 (header rows optional)

Header 2

Header 3

Header 4

body row 1, column 1

column 2

column 3

column 4

body row 2

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Lists

Bullet lists

Use the following format to create bullet lists:

  • A bullet list must have an empty line before it begins;

  • First level items use the “*” symbol;

  • No empty lines should be used in between elements;

  • If a line is too long, like this one, it must be broken into multiple lines with no more than 80 characters in each line;

  • Second level sub items use the “-” symbol;

    • A sub list must have an empty line before it begins;

    • It must be indented with two spaces more than the first level lists;

    • A sub list must have an empty line after it ends.

  • There should be an empty line after a list ends.

* A bullet list must have an empty line before it begins;
* First level items use the "*" symbol;
* No empty lines should be used in between elements;
* If a line is too long, like this one, it must be broken into multiple lines
  with no more than 80 characters in each line;
* Second level sub items use the "-" symbol;

  - A sub list must have an empty line before it begins;
  - It must be indented with two spaces more than the first level lists;
  - A sub list must have an empty line after it ends.

* There should be an empty line after a list ends.

Numbered lists

Use the following format to create numbered lists:

  1. A bullet list must have an empty line before it begins;

  2. List items must be auto-numbered using the “#” symbol;

  3. No empty lines should be used in between elements;

  4. If a line is too long, like this one, it must be broken into multiple lines with no more than 80 characters in each line.

  5. There should be an empty line after a list ends.

#. A bullet list must have an empty line before it begins;
#. List items must be auto-numbered using the "#" symbol;
#. No empty lines should be used in between elements;
#. If a line is too long, like this one, it must be broken into multiple lines
   with no more than 80 characters in each line.
#. There should be an empty line after a list ends.