How to document¶
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.
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 npor
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.
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
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
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
Modifications to numpydoc¶
Numpydoc has been modified in the following ways:
numpysphinx domain has been removed.
extra_public_methodshave been added.
:autoclass:summaries now link to full name, which allows subclassing between packages.