Building the NumPy API and reference docs#

If you only want to get the documentation, note that pre-builtversions can be found at

https://numpy.org/doc/

in several different formats.

Development environments#

Before proceeding further it should be noted that the documentation is builtwith themake tool, which is not natively available on Windows. MacOS orLinux users can jump toPrerequisites. It is recommended forWindows users to set up their development environment onGitHub Codespaces (seeRecommended development setup) orWindows Subsystem for Linux (WSL).WSL is a good option for a persistent local set-up.

Prerequisites#

Building the NumPy documentation and API reference requires the following:

NumPy#

Since large parts of the main documentation are obtained from NumPy viaimportnumpy and examining the docstrings, you will need to firstbuild and install it so that the correct version isimported.NumPy has to be re-built and re-installed every time you fetch the latest version of therepository, before generating the documentation. This ensures that the NumPy version andthe git repository version are in sync.

Note that you can e.g. install NumPy to a temporary location and setthe PYTHONPATH environment variable appropriately.Alternatively, if using Python virtual environments (via e.g.conda,virtualenv or thevenv module), installing NumPy into anew virtual environment is recommended.

Dependencies#

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

pipinstall-rrequirements/doc_requirements.txt

Note

It may be necessary to install development versions of the docdependencies to build the docs locally:

pipinstall--pre--force-reinstall--extra-index-url \https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \-rrequirements/doc_requirements.txt

We currently useSphinx along withDoxygen for generating the API andreference documentation for NumPy. In addition, building the documentationrequires the Sphinx extensionplot_directive, which is shipped withMatplotlib. We also usenumpydoc to render docstrings inthe generated API documentation.SciPyis installed since some parts of the documentation require SciPy functions.

For installingDoxygen, please check the officialdownload andinstallation pages, or if youare using Linux then you can install it through your distribution package manager.

Note

Try to install a newer version ofDoxygen > 1.8.10 otherwise you may get somewarnings during the build.

Submodules#

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

gitsubmoduleupdate--init

Instructions#

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

spindocs

This will build NumPy from source if you haven’t already, and run Sphinx tobuild thehtml docs. If all goes well, this will generate abuild/htmlsubdirectory in the/doc directory, containing the built documentation.

The documentation for NumPy distributed athttps://numpy.org/doc in html andpdf format is also built withmakedist. SeeHOWTO RELEASE for detailson how to updatehttps://numpy.org/doc.