DOC: Reorganized the documentation contribution docs (#19645)

* DOC: Reorganized documentation contribution docs

1. Removed Documentation conventions page
2. Merged A guide to NumPy documentation into How to contribute to NumPy documentation
3. Moved Building NumPy reference and docs to Development section
4. Removed the Documentation index stub

3 files changed, 190 insertions, 0 deletions

diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
index 9354357e8..3156d3452 100644
--- a/doc/source/dev/howto-docs.rst
+++ b/doc/source/dev/howto-docs.rst
@@ -153,6 +153,69 @@ if you write a tutorial on your blog, create a YouTube video, or answer question
 on Stack Overflow and other sites.
 
 
+.. _howto-document:
+
+*******************
+Documentation style
+*******************
+
+.. _userdoc_guide:
+
+User documentation
+==================
+
+- In general, we follow the
+  `Google developer documentation style guide <https://developers.google.com/style>`_
+  for the User Guide.
+
+- NumPy style governs cases where:
+
+      - Google has no guidance, or
+      - We prefer not to use the Google style
+
+  Our current rules:
+
+      - We pluralize *index* as *indices* rather than
+        `indexes <https://developers.google.com/style/word-list#letter-i>`_,
+        following the precedent of :func:`numpy.indices`.
+
+      - For consistency we also pluralize *matrix* as *matrices*.
+
+- Grammatical issues inadequately addressed by the NumPy or Google rules are
+  decided by the section on "Grammar and Usage" in the most recent edition of
+  the `Chicago Manual of Style
+  <https://en.wikipedia.org/wiki/The_Chicago_Manual_of_Style>`_.
+
+- We welcome being
+  `alerted <https://github.com/numpy/numpy/issues>`_ to cases
+  we should add to the NumPy style rules.
+
+.. _docstring_intro:
+
+Docstrings
+==========
+
+When using `Sphinx <http://www.sphinx-doc.org/>`_ in combination with the
+NumPy conventions, you should use the ``numpydoc`` extension so that your
+docstrings will be handled correctly. For example, Sphinx will extract the
+``Parameters`` section from your docstring and convert it into a field
+list.  Using ``numpydoc`` will also avoid the reStructuredText errors produced
+by plain Sphinx when it encounters NumPy docstring conventions like
+section headers (e.g. ``-------------``) that sphinx does not expect to
+find in docstrings.
+
+It is available from:
+
+* `numpydoc on PyPI <https://pypi.python.org/pypi/numpydoc>`_
+* `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
+
+Note that for documentation within NumPy, it is not necessary to do
+``import numpy as np`` at the beginning of an example.
+
+Please use the ``numpydoc`` :ref:`formatting standard <numpydoc:format>` as
+shown in their :ref:`example <numpydoc:example>`.
+
+
 *********************
 Documentation reading
 *********************
diff --git a/doc/source/dev/howto_build_docs.rst b/doc/source/dev/howto_build_docs.rst
new file mode 100644
index 000000000..884cf7935
--- /dev/null
+++ b/doc/source/dev/howto_build_docs.rst
@@ -0,0 +1,126 @@
+.. _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 can be installed
+with::
+
+    pip install -r doc_requirements.txt
+
+We currently use Sphinx_ 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.
+
+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
+
+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.txt
diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst
index b9347a58c..a8c969267 100644
--- a/doc/source/dev/index.rst
+++ b/doc/source/dev/index.rst
@@ -257,6 +257,7 @@ The rest of the story
    Git Basics <gitwash/index>
    development_environment
    development_gitpod
+   howto_build_docs
    development_workflow
    development_advanced_debugging
    reviewer_guidelines