=========================================
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

    http://docs.scipy.org/

in several different formats.

.. _Sphinx: http://sphinx.pocoo.org


Instructions
------------

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

    git submodule init
    git submodule update

In addition, building the documentation requires the Sphinx extension
`plot_directive`, which is shipped with Matplotlib_. This Sphinx extension can
be installed with or without completely installing Matplotlib: see the
Matplotlib documentation for more information.

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.

After NumPy is installed, write::

    make html

in the ``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.

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 http://docs.scipy.org in html and
pdf format is also built with ``make dist``.  See `HOWTO RELEASE`_ for details on
how to update http://docs.scipy.org.

.. _Matplotlib: http://matplotlib.org/
.. _HOWTO RELEASE: https://github.com/numpy/numpy/blob/master/doc/HOWTO_RELEASE.rst.txt

Sphinx extensions
-----------------

NumPy's documentation uses several custom extensions to Sphinx.  These
are shipped in the ``sphinxext/`` directory (as git submodules, as discussed
above), and are automatically enabled when building NumPy's documentation.

If you want to make use of these extensions in third-party
projects, they are available on PyPi_ as the numpydoc_ package.

.. _PyPi: http://python.org/pypi
.. _numpydoc: http://python.org/pypi/numpydoc