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

10 files changed, 73 insertions, 117 deletions

diff --git a/doc/source/_templates/indexcontent.html b/doc/source/_templates/indexcontent.html
index 4cbe7d4d5..450cb1e2e 100644
--- a/doc/source/_templates/indexcontent.html
+++ b/doc/source/_templates/indexcontent.html
@@ -41,8 +41,8 @@
         <span class="linkdescr">Contributing to NumPy</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("dev/underthehood") }}">Under-the-hood docs</a><br/>
 	<span class="linkdescr">Specialized, in-depth documentation</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("docs/howto_document") }}">A guide to NumPy documentation</a><br/>    
-      <p class="biglink"><a class="biglink" href="{{ pathto("docs/howto_build_docs") }}">Building the NumPy API and reference docs</a><br/>    
+      <p class="biglink"><a class="biglink" href="{{ pathto("dev/howto-docs") }}">How to contribute to the NumPy documentation</a><br/>    
+      <p class="biglink"><a class="biglink" href="{{ pathto("dev/howto_build_docs") }}">Building the NumPy API and reference docs</a><br/>    
       <p class="biglink"><a class="biglink" href="{{ pathto("benchmarking") }}">Benchmarking</a><br/>
         <span class="linkdescr">benchmarking NumPy</span></p>
       <p class="biglink"><a class="biglink" href="https://www.numpy.org/neps/index.html">NumPy Enhancement Proposals</a><br/>
@@ -55,7 +55,6 @@
       <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">Reporting bugs</a></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("release") }}">Release notes</a></p>
     </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("doc_conventions") }}">Document conventions</a></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">License of NumPy</a></p>
     </td></tr>
   </table>
@@ -70,7 +69,7 @@
   </p>
   <p>
     The preferred way to update the documentation is by submitting a pull
-    request on GitHub (see the <a href="{{ pathto("docs/index") }}">Documentation index</a>).
+    request on GitHub (see the <a href="{{ pathto("dev/howto-docs") }}">Documentation guide</a>).
     Please help us to further improve the NumPy documentation!
   </p>
 {% endblock %}
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 587307cf9..41b5cee25 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -300,6 +300,7 @@ intersphinx_mapping = {
     'scipy-lecture-notes': ('https://scipy-lectures.org', None),
     'pytest': ('https://docs.pytest.org/en/stable', None),
     'numpy-tutorials': ('https://numpy.org/numpy-tutorials', None),
+    'numpydoc': ('https://numpydoc.readthedocs.io/en/latest', None),
 }
 
 
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/docs/howto_build_docs.rst b/doc/source/dev/howto_build_docs.rst
index 884cf7935..884cf7935 100644
--- a/doc/source/docs/howto_build_docs.rst
+++ b/doc/source/dev/howto_build_docs.rst
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
diff --git a/doc/source/doc_conventions.rst b/doc/source/doc_conventions.rst
deleted file mode 100644
index e2bc419d1..000000000
--- a/doc/source/doc_conventions.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. _documentation_conventions:
-
-##############################################################################
-Documentation conventions
-##############################################################################
-
-- Names that look like :func:`numpy.array` are links to detailed
-  documentation.
-
-- Examples often include the Python prompt ``>>>``. This is not part of the
-  code and will cause an error if typed or pasted into the Python
-  shell. It can be safely typed or pasted into the IPython shell; the ``>>>``
-  is ignored.
-
-- Examples often use ``np`` as an alias for ``numpy``; that is, they assume
-  you've run::
-
-      >>> import numpy as np
-
-- If you're a code contributor writing a docstring, see :ref:`docstring_intro`.
-
-- If you're a writer contributing ordinary (non-docstring) documentation, see
-  :ref:`userdoc_guide`.
diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst
deleted file mode 100644
index ff726c67c..000000000
--- a/doc/source/docs/howto_document.rst
+++ /dev/null
@@ -1,75 +0,0 @@
-.. _howto-document:
-
-
-A Guide to NumPy Documentation
-==============================
-
-.. _userdoc_guide:
-
-User documentation
-******************
-- In general, we follow the
-  `Google developer documentation style guide <https://developers.google.com/style>`_.
-
-- 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.
-
-Some features described in this document require a recent version of
-``numpydoc``. For example, the **Yields** section was added in
-``numpydoc`` 0.6.
-
-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.  However, some
-sub-modules, such as ``fft``, are not imported by default, and you have to
-include them explicitly::
-
-  import numpy.fft
-
-after which you may use it::
-
-  np.fft.fft2(...)
-
-Please use the numpydoc `formatting standard`_ as shown in their example_
-
-.. _`formatting standard`: https://numpydoc.readthedocs.io/en/latest/format.html
-.. _example: https://numpydoc.readthedocs.io/en/latest/example.html
diff --git a/doc/source/docs/index.rst b/doc/source/docs/index.rst
deleted file mode 100644
index 7d8b1bcb4..000000000
--- a/doc/source/docs/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. _documentation:
-
-NumPy's Documentation
-=====================
-
-.. toctree::
-    :maxdepth: 2
-
-    howto_document
-    howto_build_docs
-    
diff --git a/doc/source/user/absolute_beginners.rst b/doc/source/user/absolute_beginners.rst
index 499e9ec5c..bb570f622 100644
--- a/doc/source/user/absolute_beginners.rst
+++ b/doc/source/user/absolute_beginners.rst
@@ -83,9 +83,12 @@ If you aren't familiar with this style, it's very easy to understand.
 If you see ``>>>``, you're looking at **input**, or the code that
 you would enter. Everything that doesn't have ``>>>`` in front of it
 is **output**, or the results of running your code. This is the style
-you see when you run ``python`` on the command line, but if you're using IPython, you might see a different style.
+you see when you run ``python`` on the command line, but if you're using
+IPython, you might see a different style. Note that it is not part of the
+code and will cause an error if typed or pasted into the Python
+shell. It can be safely typed or pasted into the IPython shell; the ``>>>``
+is ignored.
 
-For more information, see :ref:`documentation_conventions`.
 
 What’s the difference between a Python list and a NumPy array?
 --------------------------------------------------------------
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index b3ecc3a95..e5c51351e 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -38,8 +38,6 @@ details are found in :ref:`reference`.
    ../f2py/index
    ../glossary
    ../dev/underthehood
-   ../docs/index
    ../bugs
    ../release
-   ../doc_conventions
    ../license