Merge branch 'master' into fix-issue-10244

1 files changed, 35 insertions, 28 deletions

diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst
index cf86b7e99..ff726c67c 100644
--- a/doc/source/docs/howto_document.rst
+++ b/doc/source/docs/howto_document.rst
@@ -1,12 +1,41 @@
 .. _howto-document:
 
 
-A Guide to NumPy/SciPy Documentation
-====================================
+A Guide to NumPy Documentation
+==============================
+
+.. _userdoc_guide:
 
 User documentation
-*******************
-NumPy text documents should follow the `Google developer documentation style guide <https://developers.google.com/style>`_.
+******************
+- 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
 **********
@@ -40,29 +69,7 @@ after which you may use it::
 
   np.fft.fft2(...)
 
-.. rubric::
-    **For convenience the** `formatting standard`_ **is included below with an
-    example**
-
-.. include:: ../../sphinxext/doc/format.rst
-
-.. _example:
-
-Example Source
-==============
-
-.. literalinclude:: ../../sphinxext/doc/example.py
-
-
-
-Example Rendered
-================
-
-.. ifconfig:: python_version_major < '3'
-
-    The example is rendered only when sphinx is run with python3 and above
-
-.. automodule:: doc.example
-    :members:
+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