A Guide to NumPy 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:
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.
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
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
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:
after which you may use it: