Building the NumPy API and reference docs#
If you only want to get the documentation, note that pre-built versions can be found at
in several different formats.
Before proceeding further it should be noted that the documentation is built
make tool, which is not natively available on Windows. MacOS or
Linux users can jump to Prerequisites. It is recommended for
Windows users to set up their development environment on
GitHub Codespaces (see Recommended development setup) or
Windows Subsystem for Linux (WSL).
WSL is a good option for a persistent local set-up.
Building the NumPy documentation and API reference requires the following:
Since large parts of the main documentation are obtained from NumPy via
import numpy and examining the docstrings, you will need to first
build and install it so that the correct version is
NumPy has to be re-built and re-installed every time you fetch the latest version of the
repository, before generating the documentation. This ensures that the NumPy version and
the git repository version are in sync.
Note that you can e.g. install NumPy to a temporary location and set
the PYTHONPATH environment variable appropriately.
Alternatively, if using Python virtual environments (via e.g.
virtualenv or the
venv module), installing NumPy into a
new virtual environment is recommended.
All of the necessary dependencies for building the NumPy docs except for Doxygen can be installed with:
pip install -r doc_requirements.txt
We currently use Sphinx along with Doxygen for generating the API and reference documentation for NumPy. In addition, building the documentation requires the Sphinx extension plot_directive, which is shipped with Matplotlib. We also use numpydoc to render docstrings in the generated API documentation. SciPy is installed since some parts of the documentation require SciPy functions.
Try to install a newer version of Doxygen > 1.8.10 otherwise you may get some warnings during the build.
If you obtained NumPy via git, also get the git submodules that contain additional parts required for building the documentation:
git submodule update --init
Now you are ready to generate the docs, so write:
This will build NumPy from source if you haven’t already, and run Sphinx to
html docs. If all goes well, this will generate a
subdirectory in the
/doc directory, containing the built documentation.