Documentation style guide¶
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 Python-sphinx [1], which itself uses reStructuredText [2] syntax.
Filenames¶
Use only lowercase alphanumeric characters and -
(minus) symbol.
Suffix filenames with the .txt
extension.
Note
Usage of .rst
extension is not recommended because:
RST files are human-readable text files. Most systems natively recognize the
.txt
extension and open these files with a text editor. This is a good choice.Some programs parse
.rst
with rst2html [3], which cannot interpret some Sphinx’s directives such ascode-block
. So readers using such programs actually lose some content.As an example, well known Github [4] platform uses rst2html to render
.rst
files in its repository browser. Not only you lose content, you also lose features like links to lines.When you need to read HTML builds of the documentation, best practice is to export documentation as static builds with
sphinx-build
command, then host and serve these builds as static files. For public projects, you may have a look at services like Read the docs [5].
Whitespaces¶
Blank lines¶
Two blank lines before overlined 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:
#
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
See also Sphinx’s documentation about sections [6].
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/