A Guide to NumPy Documentation¶
User documentation¶
In general, we follow the Google developer documentation style guide.
NumPy style governs cases where:
Google has no guidance, or
We prefer not to use the Google style
Our current rules:
We pluralize index as indices rather than indexes, following the precedent of
numpy.indices.For consistency we also pluralize matrix as matrices.
Grammatical issues inadequately addressed by the NumPy or Google rules are decided by the section on “Grammar and Usage” in the most recent edition of the Chicago Manual of Style.
We welcome being alerted to cases we should add to the NumPy style rules.
Docstrings¶
When using Sphinx in combination with the
numpy conventions, you should use the numpydoc extension so that your
docstrings will be handled correctly. For example, Sphinx will extract the
Parameters section from your docstring and convert it into a field
list. Using numpydoc will also avoid the reStructuredText errors produced
by plain Sphinx when it encounters numpy docstring conventions like
section headers (e.g. -------------) that sphinx does not expect to
find in docstrings.
Some features described in this document require a recent version of
numpydoc. For example, the Yields section was added in
numpydoc 0.6.
It is available from:
Note that for documentation within numpy, it is not necessary to do
import numpy as np at the beginning of an example. However, some
sub-modules, such as fft, are not imported by default, and you have to
include them explicitly:
import numpy.fft
after which you may use it:
np.fft.fft2(...)
Please use the numpydoc formatting standard as shown in their example