Merge pull request #11347 from mattip/less-sphinx-warnings

DOC: Silence many sphinx warnings

12 files changed, 58 insertions, 39 deletions

diff --git a/doc/source/_templates/autosummary/attribute.rst b/doc/source/_templates/autosummary/attribute.rst
new file mode 100644
index 000000000..a6ed600ef
--- /dev/null
+++ b/doc/source/_templates/autosummary/attribute.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+attribute
+
+.. auto{{ objtype }}:: {{ objname }}
+
diff --git a/doc/source/_templates/autosummary/member.rst b/doc/source/_templates/autosummary/member.rst
new file mode 100644
index 000000000..f1f30e123
--- /dev/null
+++ b/doc/source/_templates/autosummary/member.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+member
+
+.. auto{{ objtype }}:: {{ objname }}
+
+
diff --git a/doc/source/_templates/autosummary/method.rst b/doc/source/_templates/autosummary/method.rst
new file mode 100644
index 000000000..8abda8677
--- /dev/null
+++ b/doc/source/_templates/autosummary/method.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+method
+
+.. auto{{ objtype }}:: {{ objname }}
+
diff --git a/doc/source/about.rst b/doc/source/about.rst
index cc3dd46b9..5ac4facbb 100644
--- a/doc/source/about.rst
+++ b/doc/source/about.rst
@@ -18,9 +18,7 @@ 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:
-NumPy derives from the old *Numeric* code base and can be used
-as a replacement for *Numeric*.  It also adds the features introduced
-by *Numarray* and can also be used to replace *Numarray*.
+Numeric and Numarray.
 
 NumPy community
 ---------------
diff --git a/doc/source/contents.rst b/doc/source/contents.rst
index fad9be76e..019dcc71d 100644
--- a/doc/source/contents.rst
+++ b/doc/source/contents.rst
@@ -8,6 +8,7 @@ NumPy manual contents
    reference/index
    f2py/index
    dev/index
+   docs/index
    release
    about
    bugs
diff --git a/doc/source/reference/arrays.indexing.rst b/doc/source/reference/arrays.indexing.rst
index ba1bfd312..62d36e28c 100644
--- a/doc/source/reference/arrays.indexing.rst
+++ b/doc/source/reference/arrays.indexing.rst
@@ -173,6 +173,7 @@ concepts to remember include:
     of arbitrary dimension.
 
 .. data:: newaxis
+   :noindex:
 
    The :const:`newaxis` object can be used in all slicing operations to
    create an axis of length one. :const:`newaxis` is an alias for
@@ -287,7 +288,7 @@ understood with an example.
 Combining advanced and basic indexing
 """""""""""""""""""""""""""""""""""""
 
-When there is at least one slice (``:``), ellipsis (``...``) or ``np.newaxis``
+When there is at least one slice (``:``), ellipsis (``...``) or :const:`newaxis`
 in the index (or the array has more dimensions than there are advanced indexes),
 then the behaviour can be more complicated. It is like concatenating the
 indexing result for each advanced index element
@@ -310,7 +311,7 @@ the subspace defined by the basic indexing (excluding integers) and the
 subspace from the advanced indexing part. Two cases of index combination
 need to be distinguished:
 
-* The advanced indexes are separated by a slice, ellipsis or newaxis.
+* The advanced indexes are separated by a slice, :const:`Ellipsis` or :const:`newaxis`.
   For example ``x[arr1, :, arr2]``.
 * The advanced indexes are all next to each other.
   For example ``x[..., arr1, arr2, :]`` but *not* ``x[arr1, :, 1]``
diff --git a/doc/source/reference/c-api.coremath.rst b/doc/source/reference/c-api.coremath.rst
index 82d248539..691f73287 100644
--- a/doc/source/reference/c-api.coremath.rst
+++ b/doc/source/reference/c-api.coremath.rst
@@ -222,7 +222,7 @@ Those can be useful for precise floating point comparison.
     Returns the previous status mask.
 
     .. versionadded:: 1.15.0
-n
+
 Complex functions
 ~~~~~~~~~~~~~~~~~
 
diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst
index 02a35cf56..8c2554a9e 100644
--- a/doc/source/reference/c-api.ufunc.rst
+++ b/doc/source/reference/c-api.ufunc.rst
@@ -94,19 +94,16 @@ Functions
 
     :param types:
        Length ``(nin + nout) * ntypes`` array of ``char`` encoding the
-       :ref:`PyArray_Descr.type_num` (built-in only) that the corresponding
+       `numpy.dtype.num` (built-in only) that the corresponding
        function in the ``func`` array accepts. For instance, for a comparison
        ufunc with three ``ntypes``, two ``nin`` and one ``nout``, where the
-       first function accepts :ref:`npy_int32` and the the second
-       :ref:`npy_int64`, with both returning :ref:`npy_bool`, ``types`` would
+       first function accepts `numpy.int32` and the the second
+       `numpy.int64`, with both returning `numpy.bool_`, ``types`` would
        be ``(char[]) {5, 5, 0, 7, 7, 0}`` since ``NPY_INT32`` is 5,
-       ``NPY_INT64`` is 7, and ``NPY_BOOL`` is 0 (on the python side, these
-       are exposed via :ref:`dtype.num`, i.e., for the example here,
-       ``dtype(np.int32).num``, ``dtype(np.int64).num``, and
-       ``dtype(np.bool_).num``, resp.).
+       ``NPY_INT64`` is 7, and ``NPY_BOOL`` is 0.
 
-        :ref:`casting-rules` will be used at runtime to find the first
-        ``func`` callable by the input/output provided.
+       :ref:`ufuncs.casting` will be used at runtime to find the first
+       ``func`` callable by the input/output provided.
 
     :param ntypes:
         How many different data-type-specific functions the ufunc has implemented.
@@ -121,8 +118,9 @@ Functions
         The name for the ufunc.  Specifying a name of 'add' or
         'multiply' enables a special behavior for  integer-typed
         reductions when no dtype is given.  If the input type is an
-        integer (or boolean) data type smaller than the size of the int_
-        data type, it will be internally upcast to the int_ (or uint)
+        integer (or boolean) data type smaller than the size of the
+        `numpy.int_` data type, it will be internally upcast to the
+        `numpy.int_` (or `numpy.uint`)
         data type.
 
     :param doc:
diff --git a/doc/source/reference/routines.numarray.rst b/doc/source/reference/routines.numarray.rst
deleted file mode 100644
index 9e84f49b9..000000000
--- a/doc/source/reference/routines.numarray.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-**********************
-Numarray compatibility
-**********************
-
-The numarray module was removed in NumPy 1.9.0.
diff --git a/doc/source/reference/routines.oldnumeric.rst b/doc/source/reference/routines.oldnumeric.rst
deleted file mode 100644
index 2120fc69e..000000000
--- a/doc/source/reference/routines.oldnumeric.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-*************************
-Old Numeric compatibility
-*************************
-
-.. currentmodule:: numpy
-
-The oldnumeric module was removed in NumPy 1.9.0.
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 792607cbe..09cae54b1 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -605,6 +605,7 @@ add_newdoc('numpy.core', 'broadcast',
 
     Examples
     --------
+
     Manually adding two vectors, using broadcasting:
 
     >>> x = np.array([[1], [2], [3]])
@@ -7223,8 +7224,8 @@ add_newdoc('numpy.core.multiarray', 'datetime_data',
 
     Get information about the step size of a date or time type.
 
-    The returned tuple can be passed as the second argument of `datetime64` and
-    `timedelta64`.
+    The returned tuple can be passed as the second argument of `numpy.datetime64` and
+    `numpy.timedelta64`.
 
     Parameters
     ----------
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 128da22c6..26ef3e235 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -3398,9 +3398,9 @@ def _median(a, axis=None, out=None, overwrite_input=False):
 def percentile(a, q, axis=None, out=None,
                overwrite_input=False, interpolation='linear', keepdims=False):
     """
-    Compute the qth percentile of the data along the specified axis.
+    Compute the q-th percentile of the data along the specified axis.
 
-    Returns the qth percentile(s) of the array elements.
+    Returns the q-th percentile(s) of the array elements.
 
     Parameters
     ----------
@@ -3467,7 +3467,7 @@ def percentile(a, q, axis=None, out=None,
 
     Notes
     -----
-    Given a vector ``V`` of length ``N``, the ``q``-th percentile of
+    Given a vector ``V`` of length ``N``, the q-th percentile of
     ``V`` is the value ``q/100`` of the way from the minimum to the
     maximum in a sorted copy of ``V``. The values and distances of
     the two nearest neighbors as well as the `interpolation` parameter
@@ -3543,7 +3543,7 @@ def percentile(a, q, axis=None, out=None,
 def quantile(a, q, axis=None, out=None,
              overwrite_input=False, interpolation='linear', keepdims=False):
     """
-    Compute the `q`th quantile of the data along the specified axis.
+    Compute the q-th quantile of the data along the specified axis.
     ..versionadded:: 1.15.0
 
     Parameters
@@ -3569,6 +3569,7 @@ def quantile(a, q, axis=None, out=None,
         This optional parameter specifies the interpolation method to
         use when the desired quantile lies between two data points
         ``i < j``:
+
             * linear: ``i + (j - i) * fraction``, where ``fraction``
               is the fractional part of the index surrounded by ``i``
               and ``j``.
@@ -3602,7 +3603,7 @@ def quantile(a, q, axis=None, out=None,
 
     Notes
     -----
-    Given a vector ``V`` of length ``N``, the ``q``-th quantile of
+    Given a vector ``V`` of length ``N``, the q-th quantile of
     ``V`` is the value ``q`` of the way from the minimum to the
     maximum in a sorted copy of ``V``. The values and distances of
     the two nearest neighbors as well as the `interpolation` parameter
@@ -3720,7 +3721,7 @@ def _quantile_ureduce_func(a, q, axis=None, out=None, overwrite_input=False,
             indices = concatenate((indices, [-1]))
 
         ap.partition(indices, axis=axis)
-        # ensure axis with qth is first
+        # ensure axis with q-th is first
         ap = np.moveaxis(ap, axis, 0)
         axis = 0
 
@@ -3753,7 +3754,7 @@ def _quantile_ureduce_func(a, q, axis=None, out=None, overwrite_input=False,
 
         ap.partition(concatenate((indices_below, indices_above)), axis=axis)
 
-        # ensure axis with qth is first
+        # ensure axis with q-th is first
         ap = np.moveaxis(ap, axis, 0)
         weights_below = np.moveaxis(weights_below, axis, 0)
         weights_above = np.moveaxis(weights_above, axis, 0)
@@ -3767,7 +3768,7 @@ def _quantile_ureduce_func(a, q, axis=None, out=None, overwrite_input=False,
         x1 = take(ap, indices_below, axis=axis) * weights_below
         x2 = take(ap, indices_above, axis=axis) * weights_above
 
-        # ensure axis with qth is first
+        # ensure axis with q-th is first
         x1 = np.moveaxis(x1, axis, 0)
         x2 = np.moveaxis(x2, axis, 0)