DOC: Replace "About NumPy" with "Document conventions"

Eliminates the unhelpful "About NumPy" title. All contents
of the original appear more prominently elsewhere,
except for the information about document conventions,
which is now the title and subject.

5 files changed, 34 insertions, 65 deletions

diff --git a/doc/source/_templates/indexcontent.html b/doc/source/_templates/indexcontent.html
index 5929e755d..6633aa9be 100644
--- a/doc/source/_templates/indexcontent.html
+++ b/doc/source/_templates/indexcontent.html
@@ -56,7 +56,7 @@
       <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("about") }}">About NumPy</a></p>
+      <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>
diff --git a/doc/source/about.rst b/doc/source/about.rst
deleted file mode 100644
index 3e83833d1..000000000
--- a/doc/source/about.rst
+++ /dev/null
@@ -1,62 +0,0 @@
-About NumPy
-===========
-
-NumPy is the fundamental package
-needed for scientific computing with Python. This package contains:
-
-- a powerful N-dimensional :ref:`array object <arrays>`
-- sophisticated :ref:`(broadcasting) functions <ufuncs>`
-- basic :ref:`linear algebra functions <routines.linalg>`
-- basic :ref:`Fourier transforms <routines.fft>`
-- sophisticated :ref:`random number capabilities <numpyrandom>`
-- tools for integrating Fortran code
-- tools for integrating C/C++ code
-
-Besides its obvious scientific uses, *NumPy* can also be used as an
-efficient multi-dimensional container of generic data. Arbitrary
-data types can be defined. This allows *NumPy* to seamlessly and
-speedily integrate with a wide variety of databases.
-
-NumPy is a successor for two earlier scientific Python libraries:
-Numeric and Numarray.
-
-NumPy community
----------------
-
-NumPy is a distributed, volunteer, open-source project. *You* can help
-us make it better; if you believe something should be improved either
-in functionality or in documentation, don't hesitate to contact us --- or
-even better, contact us and participate in fixing the problem.
-
-Our main means of communication are:
-
-- `scipy.org website <https://scipy.org/>`__
-
-- `Mailing lists <https://scipy.org/scipylib/mailing-lists.html>`__
-
-- `NumPy Issues <https://github.com/numpy/numpy/issues>`__ (bug reports go here)
-
-- `Old NumPy Trac <http://projects.scipy.org/numpy>`__ (dead link)
-
-More information about the development of NumPy can be found at our `Developer Zone <https://scipy.scipy.org/scipylib/dev-zone.html>`__.
-
-The project management structure can be found at our :doc:`governance page <dev/governance/index>`
-
-
-About this documentation
-========================
-
-Conventions
------------
-
-Names of classes, objects, constants, etc. are given in **boldface** font.
-Often they are also links to a more detailed documentation of the
-referred object.
-
-This manual contains many examples of use, usually prefixed with the
-Python prompt ``>>>`` (which is not a part of the example code). The
-examples assume that you have first entered::
-
->>> import numpy as np
-
-before running the examples.
diff --git a/doc/source/doc_conventions.rst b/doc/source/doc_conventions.rst
new file mode 100644
index 000000000..e2bc419d1
--- /dev/null
+++ b/doc/source/doc_conventions.rst
@@ -0,0 +1,23 @@
+.. _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
index 9f9068ab3..5a36fa718 100644
--- a/doc/source/docs/howto_document.rst
+++ b/doc/source/docs/howto_document.rst
@@ -4,10 +4,15 @@
 A Guide to NumPy/SciPy Documentation
 ====================================
 
+.. _userdoc_guide:
+
 User documentation
 *******************
 NumPy text documents should follow the `Google developer documentation style guide <https://developers.google.com/style>`_.
 
+
+.. _docstring_intro:
+
 Docstrings
 **********
 
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index 3a79f0f2e..11a019b48 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -26,7 +26,10 @@ classes contained in the package, see the :ref:`reference`.
    howtos_index
 
 
-.. These are stuck here to avoid the "WARNING: document isn't included in any
+.. Links to these files are placed directly in the top-level html
+   (doc/source/_templates/indexcontent.html, which appears for the URLs
+   numpy.org/devdocs and numpy.org/doc/XX) and are not in any toctree, so
+   we include them here to avoid a "WARNING: document isn't included in any
    toctree" message
 
 .. toctree::
@@ -39,5 +42,5 @@ classes contained in the package, see the :ref:`reference`.
    ../docs/index
    ../bugs
    ../release
-   ../about
+   ../doc_conventions
    ../license