Docstring Conventions

For the documentation we follow the Numpy docstring conventions. Example docstrings are given below.

Docstring Content

You may write doctests in the Examples section to give more detail about a function
Subclasses do not document methods/attributes from superclass that are not overwritten
Functionality relevant to users that is added to a class with magic methods like an extended ==, the in keyword etc. is documented in the Notes section of the class docstring

Attributes of a class, that are also Parameters, are not documented in a redundant way.

DO

"""
Parameters
----------
fct : function
    Function defining the net.
parameters : dict (default=tuple(()))
    Parameters of `fct`.

Attributes
----------
fct
parameters : ddg.parameters.Parameters
"""

DON’T

"""
Parameters
----------
fct : function
    Function defining the net.
parameters : dict (default=tuple(()))
    Parameters of `fct`.

Attributes
----------
fct : function
    Function defining the net.
parameters : ddg.parameters.Parameters
    Parameters of `fct`.
"""

Naming & Reference

Numpy arrays are referred to by “numpy.ndarray of shape (n,m)”
Keyword arguments are marked as such by stating the default value the folowing way: “param : bool (default=True)”

Mathematical Equations

In the notes section or in the description body of the docstring (the paragraph), mathematical equations can be written in ascii art or in pseudocode, so that it is readable in the docstring

for ascii art to display correctly, add :: before the ascii art paragraph, or put back ticks ` around inline equations, as in:

def fourth_point_from_cross_ratio(z, z1, z2, q):
    """
    Get `z12` such that `cr(z, z1, z12, z2) = q`

    For a quadrilateral of the form ::

         z2 ----- z12
          |        |
          |        |
          |        |
          z ----- z1

    with given `z,z1,z2` and `q`, compute `z12` ."""

using back ticks also prevents sphinx from interpreting part of your equation as markdown delimiters such as * and _
you can use the software sage for ascii art.
If you want to explain a LOT of math, you can put it into the user’s guide section for mathematical background. As explained in the users guide conventions, there math should be written in latex.

Example: Function Docstring

def func(arg1, arg2):
    """A short (up to 50 characters) summary that does not use variable names or the function name.

    [Extended description of function, used to clarify functionality, not to discuss
    implementation details or background theory, which should rather be done in a
    Notes section.]

    Parameters
    ----------
    arg1 : int
        Description of `arg1` and possible default value
    arg2 : iterable object
        Description of `arg2`

    Returns
    -------
    bool
        Description of return value

    Raises
    ------
    ValueError
        Description of what raises an exception of the above type

    Warns
    -----
    UserWarning
        Description of what raises a warning of this type, similar
        to the "Raises" section

    Warnings
    --------
    Things the user should be aware of! Rendered as a red warning box.

    Notes
    -----
    Optional section that provides additional information about the code, further
    details about the algorithm and implementation.
    """
    return True

Layout

To keep indention and line breaks, you may use vertical lines in front of the docstring:

"""
create_spheres : bool
    | If true, spheres will be created around the vertices of the resulting
    | Delaunay surface.
    |    light blue: original vertices
    |    white: vertices introduced for visualization,
    | Default: True
"""

Example: Class Docstring

class Net(Transformable, Callable, Updatable, UpdateTrigger):
    """Base class for nets.

    Parameters
    ----------
    fct : function
        Function defining the net.
    domain : ddg.nets.Domain or list of intervals
        Domain of `fct`.
    name : str (default='Net')
        Name of the net (mostly used for blender conversion).

    Attributes
    ----------
    fct : function
        Function defining the net.
    domain : ddg.nets.Domain
        Domain of `fct`.
    parameters : ddg.nets.Parameters
        Parameters of `fct`.
    name : str
        Name of the net (mostly used for blender conversion).
    changed : bool
        This argument is set `True` when the parameters of the net
        are not in their original state.
    dimension : int
        Dimension of the domain.

    Notes
    -----
    Instances of this class are callable. Calling a net will return the output
    of `fct` transformed with any transformations that were applied using
    `transform`.

    See Also
    --------
    SmoothNet, DiscreteNet, NetCollection
    """

Quirks with the Methods section

The Methods section in the docstring is considered optional. It also works differently than the other sections in the generated html documentation: It will generate a table instead of a list in the style of e.g. the Parameters section:

The short description comes from the first line of the docstring of the method.

You can also write your own descriptions if the method doesn’t have its own docstring. If it does, these will simply be ignored in the generated documentation, but they might still be useful for people reading the code.

"""
Methods
-------
another_method
    This is another method
the_second_one
    This is the second method
"""

produces

Never mix the two styles because it will look terrible:

This means that either all or none of the listed methods must have their own docstrings.