Documentation style

Document you code! Code without or with poor documentation will probably never be used by someone else. That’s a fact. Do you want to use code of which you have no idea what it does or how it does a specific task? Especially in the scientific community it is important how the code works and what the underlying mathematical (or whatever scientific) principles are.

The documentation of this project is built with Sphinx and hosted on Read the Docs. Hence, the languages for docstrings is reStructuredText (comments are not part of the documentations and are thus written in plain text).

For comments and docstrings follow the general style guide PEP 257. For docstrings follow the special NumPy docstring convention. A very brief summary:

• Give every function, class or whatever object a docstring!

• The docstrings should contain a description what the object does, what input parameters it needs and what it returns. If the object solves a scientific problem, it should also be explained how that problem is solved in a separate Notes section.

• Contrary to what is mentioned in the NumPy docstring convention, the Examples section serves also as code test via doctest, as long as we have not implemented extensive test suites using pytest.

• Since text editors usually use a mono-spaced font, put two spaces between the end of a sentence and the beginning of a new sentence.

• Scripts get a complete docstring at the module level (that means before the import statements) such that the script’s documentation can be auto-generated with sphinx.ext.autodoc. The docstring convention for scripts is similar to the docstring convention for functions. However, some changes apply:

  • The Parameters section is replaced by an Options section

  • In the Options section, use a reStructuredText option list to list the options with which the script can/must be called and their meaning.

  • The Returns section is replaced by an optional Output section, which for instance can contain a list of files which are created by the script.

  • The Notes section should contain a detailed description of the scientific problem which is solved by the script and particularly how it is solved.

  • The docstring must contain at least one particular use case in the Examples section, preferably with an image rendering the data generated by the script in a plot.

  • Note that you will have to repeat parts of your docstring (especially the summary and a potentially abbreviated version of the Options section) when implementing the command-line interface with argparse.

Convention for section levels in the documentation:

• Parts: Over- and underlined with #

• Chapters: Over- and underlined with *

• Sections: Underlined with =

• Subsections: Underlined with - (also used in docstrings of functions and other objects. See the NumPy docstring convention)

• Subsubsections: Underlined with ^

• Paragraphs: Underlined with "

• Subparagraphs: Underlined with '

Order of characters in nested bullet lists: “*”, “-“, “+”.