Building the NumPy API and reference docs
We currently use Sphinx for generating the API and reference documentation for Numpy. You will need Sphinx 1.0.1 or newer.
If you only want to get the documentation, note that pre-built versions can be found at
in several different formats.
Since large parts of the main documentation are stored in docstrings, you will need to first build Numpy, and install it so that the correct version is imported by
>>> import numpy
Note that you can eg. install Numpy to a temporary location and set
the PYTHONPATH environment variable appropriately. Also note that if
you have a system Numpy installed via Python eggs, you will also need
setupegg.py to install the temporary Numpy.
After Numpy is installed, write:
doc/ directory. If all goes well, this will generate a
build/html subdirectory containing the built documentation. Note
that building the documentation on Windows is currently not actively
supported, though it should be possible. (See Sphinx documentation
for more information.)
To build the PDF documentation, do instead:
make latex make -C build/latex all-pdf
You will need to have Latex installed for this.
In addition to the above, you can also do:
which will rebuild Numpy, install it to a temporary location, and build the documentation in all formats. This will most likely again only work on Unix platforms.
Numpy's documentation uses several custom extensions to Sphinx. These
are shipped in the
sphinxext/ directory, and are automatically
enabled when building Numpy's documentation.
In addition, you will need to add:
extensions = ['numpydoc']
conf.py in your Sphinx documentation.
The following extensions are available:
numpydoc: support for Numpy docstring format in Sphinx.
numpydoc.plot_directives: Adaptation of Matplotlib's
plot::directive. Note that this implementation may still undergo severe changes or be eventually deprecated.
numpydoc.autosummary: (DEPRECATED) An
autosummary::directive. Available in Sphinx 0.6.2 and (to-be) 1.0 as
sphinx.ext.autosummary, and it the Sphinx 1.0 version is recommended over that included in Numpydoc.
numpydoc.traitsdoc: For gathering documentation about Traits attributes.