How to document

ODL is documented using Sphinx and a modified version of numpydoc. An example documentation is given below.

class MyClass(object):

    """Calculate important things.

    The first line summarizes the class, after that comes a blank
    line followed by a more detailed description (both optional).
    Confine the docstring to 72 characters per line. In general, try
    to follow `PEP257`_ in the docstring style.

    Docstrings can have sections with headers, signalized by a
    single-dash underline, e.g. "References". Check out
    `Numpydoc`_ for the recognized section labels.

    References
    ----------
    .. _PEP257: https://www.python.org/dev/peps/pep-0257/
    .. _Numpydoc: https://github.com/numpy/numpy/blob/master/doc/\
HOWTO_DOCUMENT.rst.txt
    """

    def __init__(self, c, parameter=None):
        """Initializer doc goes here.

        Parameters
        ----------
        c : float
            Constant to scale by.
        parameter : float, optional
            Some extra parameter.
        """
        self.c = c
        self.parameter = parameter

    def my_method(self, x, y):
        """Calculate ``c * (x + y)``.

        The first row is a summary, after that comes
        a more detailed description.

        Parameters
        ----------
        x : float
            First summand.
        y : float
            Second summand.

        Returns
        -------
        scaled_sum : float
            Result of ``c * (x + y)``.

        Examples
        --------
        Examples should be working pieces of code and are checked with
        ``doctest`` for consistent output.

        >>> obj = MyClass(5)
        >>> obj(3, 5)
        8.0
        """
        return self.c * (x + y)

     def my_other_method(self):
         """Print the parameter.

         See Also
         --------
         my_method : some calculation, but not much
         """
         print(self.parameter)

Some short tips

• Text within backticks: `some_target` will create a link to the target (e.g. `numpy.ndarray`).

• Make sure that the first line is short and descriptive.

• Examples are often better than long descriptions.

• Numpy and ODL are both imported by default in doctests, so there is no need for import numpy as np or import odl.

Quick summary of PEP257

• Write docstrings always with triple double quotes """, even one-liners.

• Class docstrings are separated from the class definition line by a blank line, functions and methods begin directly in the next line.

• Use imperative style (“Calculate”, not “Calculates”) in the summary (=first) line and end it with a full stop. Do not add a space after the opening triple quotes.

• For one-liners: put the closing quotes on the same line. Otherwise: make a new line for the closing quotes.

• Document at least all public methods and attributes.

Advanced

This section covers advanced topics for developers that need to change internals of the documentation.

Re-generating the doc

The HTML documentation is generated by running make html in the doc/ folder. Autosummary currently does not support nested modules, so to handle this, we auto-generate .rst files for each module. This is done in each invocation of make html. If results are inconsistent after changing code (or switching branches), e.g. warnings about missing modules appear, run make clean an build the docs from scratch with make html.

Modifications to numpydoc

Numpydoc has been modified in the following ways:

• The numpy sphinx domain has been removed.

• More extra_public_methods have been added.

• :autoclass: summaries now link to full name, which allows subclassing between packages.