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

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
to use ``setupegg.py`` to install the temporary Numpy.

After Numpy is installed, write::

    make html

in this ``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::

   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.


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

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.

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
