Merge pull request #17391 from bjnath/doc-conventions

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

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 7cd97b954..ff726c67c 100644
--- a/doc/source/docs/howto_document.rst
+++ b/doc/source/docs/howto_document.rst
@@ -4,6 +4,8 @@
 A Guide to NumPy Documentation
 ==============================
 
+.. _userdoc_guide:
+
 User documentation
 ******************
 - In general, we follow the
@@ -32,6 +34,9 @@ User documentation
   we should add to the NumPy style rules.
 
 
+
+.. _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