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:

• numpydoc on PyPI
• numpydoc on GitHub

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