BLD: Add requirements.txt file for building docs (#15778)

* BLD: Added doc_requirements.txt and improve documentation around building docs

3 files changed, 34 insertions, 11 deletions

diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst
index 1aacc2c49..b5c7d297b 100644
--- a/doc/source/dev/index.rst
+++ b/doc/source/dev/index.rst
@@ -198,6 +198,13 @@ Pull requests (PRs) that modify code should either have new tests, or modify exi
 tests to fail before the PR and pass afterwards. You should :ref:`run the tests
 <development-environment>` before pushing a PR.
 
+Running NumPy's test suite locally requires some additional packages, such as
+``pytest`` and ``hypothesis``. The additional testing dependencies are listed
+in ``test_requirements.txt`` in the top-level directory, and can conveniently
+be installed with::
+
+    pip install -r test_requirements.txt
+
 Tests for a module should ideally cover all code in that module,
 i.e., statement coverage should be at 100%.
 
@@ -231,6 +238,11 @@ Requirements
 `Sphinx <http://www.sphinx-doc.org/en/stable/>`__ is needed to build
 the documentation. Matplotlib, SciPy, and IPython are also required.
 
+These additional dependencies for building the documentation are listed in
+``doc_requirements.txt`` and can be conveniently installed with::
+
+    pip install -r doc_requirements.txt
+
 The numpy documentation also depends on the
 `numpydoc <https://numpydoc.readthedocs.io/en/latest/>`__ sphinx extension
 as well as an external sphinx theme.
diff --git a/doc/source/docs/howto_build_docs.rst b/doc/source/docs/howto_build_docs.rst
index f46070d78..29912a5af 100644
--- a/doc/source/docs/howto_build_docs.rst
+++ b/doc/source/docs/howto_build_docs.rst
@@ -5,12 +5,12 @@ Building the NumPy API and reference docs
 =========================================
 
 We currently use Sphinx_ for generating the API and reference
-documentation for NumPy.  You will need Sphinx >= 2.0.0.
+documentation for NumPy.  You will need Sphinx >= 2.2.0.
 
 If you only want to get the documentation, note that pre-built
 versions can be found at
 
-    https://docs.scipy.org/
+    https://numpy.org/doc/
 
 in several different formats.
 
@@ -23,23 +23,30 @@ 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
+    git submodule update --init
 
 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.
+be installed by installing Matplotlib. You will also need Python>=3.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.
 
+After NumPy is installed, install SciPy since some of the plots in the random
+module require `scipy.special` to display properly.
+
 Note that you can eg. 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.
+All of the necessary dependencies for building the NumPy docs can be installed
+with::
 
-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::
+    pip install -r doc_requirements.txt
+
+Now you are ready to generate the docs, so write::
 
     make html
 
@@ -69,9 +76,9 @@ 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.
+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.
 
 .. _Matplotlib: https://matplotlib.org/
 .. _HOWTO RELEASE: https://github.com/numpy/numpy/blob/master/doc/HOWTO_RELEASE.rst.txt
diff --git a/doc_requirements.txt b/doc_requirements.txt
new file mode 100644
index 000000000..ce1c33b17
--- /dev/null
+++ b/doc_requirements.txt
@@ -0,0 +1,4 @@
+sphinx>=2.2.0
+ipython
+scipy
+matplotlib