A guide to GBSpy documentation process

GBSpy uses the Sphinx document generator to parse the code and generate the API documentation. To this end, it uses the Python documentation strings, a.k.a. docstrings, as a source for documentation. This has two main advantages:

1. All the documentation is in one place, i.e. in the code. There is no need to write the documentation in multiple places, which is tedious and error prone.

2. Since all the documentation stems from the Python docstrings, it encourages developers to write them.

Docstring standard

For Sphinx to work properly, the docstrings must follow a certain standard that it can understand. Since the default reStructuredText syntax is a bit unreadable, it has been chosen to follow the numpy convention.

A docstring is surrounded by a pair of triple double quotes, i.e. ". The first line is a short one-line summary describing the purpose of the Python object. It is followed by a blank line and then, a longer more detailed description if needed.

Here is an example of a minimal docstring:

"""
An minimal docstring example
"""

and here is a more complete one:

"""
A more complete docstring example

In this new paragraph, I can put a more detailed description of my Python
object. In general try to have lines with less than 75 characters so that it
will print nicely in terminals.
"""

Adding parameters and return values

Description of function arguments and return values are defined using the keywords Parameters and Returns underlined with hyphens (-):

"""
Parameters
----------
x : type
    Description of what ``x`` is.

y
    Description of parameter ``y``. Note the absence of colon if you don't
    add a type to the parameter.

a1, a2
    You can also group similar arguments in one entry.

Returns
-------
type
    Very similar documentation for return values.
"""

Examples

One of the awesome feature of Sphinx is that it can extract examples from the docstrings. You only need to append >>> to every python command:

>>> print("Hello!")
Hello!

>>> 2+3
5

Note that multiple examples must be separated by a blank line.

Python classes

Python classes have a few additional keywords that you can use to describe their attributes (Attributes), or their methods (Methods).

Other keywords

There are other keywords similar to Parameters and Returns that you can use, e.g Raises for exceptions, See Also for similar content, or References for references. Have a look at the numpy docstring standard for more information.