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.

Development environments

Before proceeding further it should be noted that the documentation is built with the 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 Gitpod or Windows Subsystem for Linux (WSL). WSL is a good option for a persistent local set-up.

Gitpod

Gitpod is an open-source platform that automatically creates the correct development environment right in your browser, reducing the need to install local development environments and deal with incompatible dependencies.

If you have good internet connectivity and want a temporary set-up, it is often faster to build with Gitpod. Here are the in-depth instructions for building NumPy with Gitpod.

Prerequisites

Building the NumPy documentation and API reference requires the following:

NumPy

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 imported. 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. conda, virtualenv or the venv module), installing NumPy into a new virtual environment is recommended.

Dependencies

All of the necessary dependencies for building the NumPy docs can be installed with:

pip install -r doc_requirements.txt

We currently use Sphinx 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.

Submodules

If you obtained NumPy via git, also get the git submodules that contain additional parts required for building the documentation:

git submodule update --init

Instructions

Now you are ready to generate the docs, so write:

cd doc
make html

If all goes well, this will generate a build/html subdirectory in the /doc directory, containing the built documentation. If you get a message about installed numpy != current repo git version, you must either override the check by setting GITVER or re-install NumPy.

If you have built NumPy into a virtual environment and get an error that says numpy not found, cannot build documentation without..., you need to override the makefile PYTHON variable at the command line, so instead of writing make  html write:

make PYTHON=python html

To build the PDF documentation, do instead:

make latex
make -C build/latex all-pdf

You will need to have LaTeX installed for this, inclusive of support for Greek letters. For example, on Ubuntu xenial texlive-lang-greek and cm-super are needed. Also, latexmk is needed on non-Windows systems.

Instead of the above, you can also do:

make dist

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.

The documentation for NumPy distributed at https://numpy.org/doc in html and pdf format is also built with make dist. See HOWTO RELEASE for details on how to update https://numpy.org/doc.