We use Sphinx to embed code documentations in source files, as Python docstrings. Sphinx uses the reStructuredText markup language. Sphinx and its Python support, as well as reST markup, have various quirks that demand discipline.

Python Formatting

Our goals are readability and clarity.

1. Python docstrings should always appear on the line underneath the symbol they are attached to.
2. Docstrings will be indented once off the symbol they are attached to.
3. We will normally use multi-line docstrings with triple-double-quote delimiters.
4. The delimiters will each appear on their own line. (Note that in some Python guides, the first delimiter does not appear on its own line. The archaic reason for this is that it adds an extra newline at the beginning of the docstring, but this is irrelevant when one uses markup languages like reST.)
5. We will normally add an extra empty line after the docstring, neatly separate it from code.

If the docstring is very short, it's permissible to put delimiters and content all in one line and avoid the extra empty line.

English Description

The point is to succinctly describe what the symbol is for, what it does, and how to use it.

If its usage is specific, it would also be good to specify where it is used (which modules, classes, mechanisms, etc.).

Markup