blob: 35fe95fa45dcf1334cfda076fc3c5f03a9c6272e (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
.. _howto-document:
A Guide to NumPy/SciPy Documentation
====================================
When using `Sphinx <http://sphinx.pocoo.org/>`__ 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 <http://pypi.python.org/pypi/numpydoc>`_
* `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
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(...)
.. rubric:: **For convenience the** `formatting standard`_ **is included below.**
.. include:: ../../sphinxext/doc/format.rst
.. _`formatting standard`: https://numpydoc.readthedocs.io/en/latest/format.html
|
