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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
.. _howto-build-docs:
=========================================
Building the NumPy API and reference docs
=========================================
If you only want to get the documentation, note that pre-built
versions 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 built with the ``make`` tool,
which is not natively available on Windows. MacOS or Linux users can jump
to :ref:`how-todoc.prerequisites`. It is recommended for Windows users to set up their development
environment on :ref:`Gitpod <development-gitpod>` or `Windows Subsystem
for Linux (WSL) <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. WSL is a good option
for a persistent local set-up.
Gitpod
~~~~~~
Gitpod is an open-source platform that automatically creates the correct development environment right
in your browser, reducing the need to install local development environments and deal with
incompatible dependencies.
If you have good internet connectivity and want a temporary set-up,
it is often faster to build with Gitpod. Here are the in-depth instructions for
:ref:`building NumPy with Gitpod <development-gitpod>`.
.. _how-todoc.prerequisites:
Prerequisites
=============
Building the NumPy documentation and API reference requires the following:
NumPy
~~~~~
Since large parts of the main documentation are obtained from NumPy via
``import numpy`` and examining the docstrings, you will need to first
:ref:`build <building-from-source>` and install it so that the correct version is imported.
NumPy has to be re-built and re-installed every time you fetch the latest version of the
repository, before generating the documentation. This ensures that the NumPy version and
the git repository version are in sync.
Note that you can e.g. install NumPy to a temporary location and set
the PYTHONPATH environment variable appropriately.
Alternatively, if using Python virtual environments (via e.g. ``conda``,
``virtualenv`` or the ``venv`` module), installing NumPy into a
new virtual environment is recommended.
Dependencies
~~~~~~~~~~~~
All of the necessary dependencies for building the NumPy docs except for
Doxygen_ can be installed with::
pip install -r doc_requirements.txt
We currently use Sphinx_ along with Doxygen_ for generating the API and
reference documentation for NumPy. In addition, building the documentation
requires the Sphinx extension `plot_directive`, which is shipped with
:doc:`Matplotlib <matplotlib:index>`. We also use numpydoc_ to render docstrings in
the generated API documentation. :doc:`SciPy <scipy:index>`
is installed since some parts of the documentation require SciPy functions.
For installing Doxygen_, please check the official
`download <https://www.doxygen.nl/download.html#srcbin>`_ and
`installation <https://www.doxygen.nl/manual/install.html>`_ pages, or if you
are using Linux then you can install it through your distribution package manager.
.. note::
Try to install a newer version of Doxygen_ > 1.8.10 otherwise you may get some
warnings during the build.
Submodules
~~~~~~~~~~
If you obtained NumPy via git, also get the git submodules that contain
additional parts required for building the documentation::
git submodule update --init
.. _Sphinx: http://www.sphinx-doc.org/
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/index.html
.. _Doxygen: https://www.doxygen.nl/index.html
Instructions
============
Now you are ready to generate the docs, so write::
cd doc
make html
If all goes well, this will generate a
``build/html`` subdirectory in the ``/doc`` directory, 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.
If you have built NumPy into a virtual environment and get an error
that says ``numpy not found, cannot build documentation without...``,
you need to override the makefile ``PYTHON`` variable at the command
line, so instead of writing ``make html`` write::
make PYTHON=python html
To build the PDF documentation, do instead::
make latex
make -C build/latex all-pdf
You will need to have LaTeX_ installed for this, inclusive of support for
Greek letters. For example, on Ubuntu xenial ``texlive-lang-greek`` and
``cm-super`` are needed. Also, ``latexmk`` is needed on non-Windows systems.
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://numpy.org/doc in html and
pdf format is also built with ``make dist``. See `HOWTO RELEASE`_ for details
on how to update https://numpy.org/doc.
.. _LaTeX: https://www.latex-project.org/
.. _HOWTO RELEASE: https://github.com/numpy/numpy/blob/main/doc/HOWTO_RELEASE.rst
|
