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
orimport 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.