1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
=========================================
Building the NumPy API and reference docs
=========================================
We currently use Sphinx_ for generating the API and reference
documentation for Numpy. You will need Sphinx 0.5 or newer. Sphinx's
current development version also works as of now (2009-06-24), and
using it is recommended though not required.
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
------------
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.
However, if you want to make use of these extensions in third-party
projects, they are available on PyPi_ as the numpydoc_ package, and
can be installed with::
easy_install numpydoc
In addition, you will need to add::
extensions = ['numpydoc']
to ``conf.py`` in your Sphinx documentation.
The following extensions are available:
- ``numpydoc``: support for Numpy docstring format in Sphinx.
- ``numpydoc.only_directives``: (DEPRECATED)
- ``numpydoc.plot_directives``: Adaptation of Matplotlib's ``plot::``
directive. Note that this implementation may still undergo severe
changes or be eventually deprecated.
- ``numpydoc.autosummary``: (DEPRECATED) An ``autosummary::`` directive.
Available in Sphinx 0.6.2 and (to-be) 1.0 as ``sphinx.ext.autosummary``,
and it the Sphinx 1.0 version is recommended over that included in
Numpydoc.
- ``numpydoc.traitsdoc``: For gathering documentation about Traits attributes.
.. _PyPi: http://python.org/pypi
.. _numpydoc: http://python.org/pypi/numpydoc
|
