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
|
.. _howto-build-docs:
=========================================
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.8.3 <= 1.8.5.
If you only want to get the documentation, note that pre-built
versions can be found at
https://docs.scipy.org/
in several different formats.
.. _Sphinx: http://www.sphinx-doc.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 by installing Matplotlib. You will also need python3.6.
Since large parts of the main documentation are obtained from numpy via
``import numpy`` and examining the docstrings, you will need to first build
NumPy, and install it so that the correct version is imported.
Note that you can eg. install NumPy to a temporary location and set
the PYTHONPATH environment variable appropriately.
After NumPy is installed, install SciPy since some of the plots in the random
module require `scipy.special` to display properly. Now you are ready to
generate the docs, so write::
make html
in the ``doc/`` directory. If all goes well, this will generate a
``build/html`` subdirectory 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.
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 https://docs.scipy.org in html and
pdf format is also built with ``make dist``. See `HOWTO RELEASE`_ for details on
how to update https://docs.scipy.org.
.. _Matplotlib: https://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: https://pypi.org/
.. _numpydoc: https://python.org/pypi/numpydoc
|
