DOC: add new glossary terms (#17263)

* DOC: add new glossary terms

* DOC: link to python Ellipsis

* DOC: fixes from review

* DOC: fixes from review

* DOC: remove glossary items that belong to python

2 files changed, 262 insertions, 20 deletions

diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst
index d37534960..4a59c990b 100644
--- a/doc/source/glossary.rst
+++ b/doc/source/glossary.rst
@@ -2,10 +2,98 @@
 Glossary
 ********
 
-.. toctree::
-
 .. glossary::
 
+
+   (`n`,)
+       A tuple with one element. The trailing comma distinguishes a one-element
+       tuple from a parenthesized ``n``.
+
+
+   -1
+       Used as a dimension entry, ``-1`` instructs NumPy to choose the length
+       that will keep the total number of elements the same.
+
+
+   ``...``
+       An :py:data:`Ellipsis`
+
+       **When indexing an array**, shorthand that the missing axes, if they
+       exist, are full slices.
+
+           >>> a = np.arange(24).reshape(2,3,4)
+
+           >>> a[...].shape
+           (2, 3, 4)
+
+           >>> a[...,0].shape
+           (2, 3)
+
+           >>> a[0,...].shape
+           (3, 4)
+
+           >>> a[0,...,0].shape
+           (3,)
+
+       It can be used at most once; ``a[...,0,...]`` raises an :exc:`IndexError`.
+
+       **In printouts**, NumPy substitutes ``...`` for the middle elements of
+       large arrays. To see the entire array, use `numpy.printoptions`
+
+
+   ``:``
+       The Python :term:`python:slice`
+       operator. In ndarrays, slicing can be applied to every
+       axis:
+
+           >>> a = np.arange(24).reshape(2,3,4)
+           >>> a
+           array([[[ 0,  1,  2,  3],
+                   [ 4,  5,  6,  7],
+                   [ 8,  9, 10, 11]],
+           <BLANKLINE>
+                  [[12, 13, 14, 15],
+                   [16, 17, 18, 19],
+                   [20, 21, 22, 23]]])
+           <BLANKLINE>
+           >>> a[1:,-2:,:-1]
+           array([[[16, 17, 18],
+                   [20, 21, 22]]])
+
+       Trailing slices can be omitted: ::
+
+           >>> a[1] == a[1,:,:]
+           array([[ True,  True,  True,  True],
+                  [ True,  True,  True,  True],
+                  [ True,  True,  True,  True]])
+
+       In contrast to Python, where slicing creates a copy, in NumPy slicing
+       creates a :term:`view`.
+
+       For details, see :ref:`combining-advanced-and-basic-indexing`.
+
+
+   ``<``
+       In a dtype declaration, indicates that the data is
+       :term:`little-endian` (the bracket is big on the right). ::
+
+           >>> dt = np.dtype('<f')  # little-endian single-precision float
+
+
+   ``>``
+       In a dtype declaration, indicates that the data is
+       :term:`big-endian` (the bracket is big on the left). ::
+
+           >>> dt = np.dtype('>H')  # big-endian unsigned short
+
+
+   advanced indexing
+       Rather than using a :doc:`scalar <reference/arrays.scalars>` or slice as
+       an index, an axis can be indexed with an array, providing fine-grained
+       selection. This is known as :ref:`advanced indexing<advanced-indexing>`
+       or "fancy indexing".
+
+
    along an axis
        Axes are defined for arrays with more than one dimension.  A
        2-dimensional array has two corresponding axes: the first running
@@ -26,6 +114,7 @@ Glossary
          >>> x.sum(axis=1)
          array([ 6, 22, 38])
 
+
    array
        A homogeneous container of numerical elements.  Each element in the
        array occupies a fixed amount of memory (hence homogeneous), and
@@ -50,19 +139,92 @@ Glossary
 
        Fast element-wise operations, called a :term:`ufunc`, operate on arrays.
 
+
    array_like
        Any sequence that can be interpreted as an ndarray.  This includes
        nested lists, tuples, scalars and existing arrays.
 
+
+   array scalar
+       For uniformity in handling operands, NumPy treats
+       a :doc:`scalar <reference/arrays.scalars>` as an array of zero
+       dimension.
+
+
+   axis
+
+       Another term for an array dimension. Axes are numbered left to right;
+       axis 0 is the first element in the shape tuple.
+
+       In a two-dimensional vector, the elements of axis 0 are rows and the
+       elements of axis 1 are columns.
+
+       In higher dimensions, the picture changes. NumPy prints
+       higher-dimensional vectors as replications of row-by-column building
+       blocks, as in this three-dimensional vector:
+
+           >>> a = np.arange(12).reshape(2,2,3)
+           >>> a
+           array([[[ 0,  1,  2],
+                   [ 3,  4,  5]],
+           <BLANKLINE>
+                  [[ 6,  7,  8],
+                   [ 9, 10, 11]]])
+
+       ``a`` is depicted as a two-element array whose elements are 2x3 vectors.
+       From this point of view, rows and columns are the final two axes,
+       respectively, in any shape.
+
+       This rule helps you anticipate how a vector will be printed, and
+       conversely how to find the index of any of the printed elements. For
+       instance, in the example, the last two values of 8's index must be 0 and
+       2. Since 8 appears in the second of the two 2x3's, the first index must
+       be 1:
+
+           >>> a[1,0,2]
+           8
+
+       A convenient way to count dimensions in a printed vector is to
+       count ``[`` symbols after the open-parenthesis. This is
+       useful in distinguishing, say, a (1,2,3) shape from a (2,3) shape:
+
+           >>> a = np.arange(6).reshape(2,3)
+           >>> a.ndim
+           2
+           >>> a
+           array([[0, 1, 2],
+                  [3, 4, 5]])
+
+           >>> a = np.arange(6).reshape(1,2,3)
+           >>> a.ndim
+           3
+           >>> a
+           array([[[0, 1, 2],
+                   [3, 4, 5]]])
+
+
+   .base
+
+       If an array does not own its memory, then its
+       :doc:`base <reference/generated/numpy.ndarray.base>` attribute
+       returns the object whose memory the array is referencing. That object
+       may be borrowing the memory from still another object, so the
+       owning object may be ``a.base.base.base...``. Despite advice to the
+       contrary, testing ``base`` is not a surefire way to determine if two
+       arrays are :term:`view`\ s.
+
+
    big-endian
        When storing a multi-byte value in memory as a sequence of bytes, the
        sequence addresses/sends/stores the most significant byte first (lowest
        address) and the least significant byte last (highest address). Common in
        micro-processors and used for transmission of data over network protocols.
 
+
    BLAS
        `Basic Linear Algebra Subprograms <https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_
 
+
    broadcast
        NumPy can do operations on arrays whose shapes are mismatched::
 
@@ -82,9 +244,11 @@ Glossary
 
        See `basics.broadcasting` for more information.
 
+
    C order
        See `row-major`
 
+
    column-major
        A way to represent items in a N-dimensional array in the 1-dimensional
        computer memory. In column-major order, the leftmost index "varies the
@@ -100,6 +264,11 @@ Glossary
        Column-major order is also known as the Fortran order, as the Fortran
        programming language uses it.
 
+   copy
+
+       See :term:`view`.
+
+
    decorator
        An operator that transforms a function.  For example, a ``log``
        decorator may be defined to print debugging information upon
@@ -124,6 +293,7 @@ Glossary
        Logging call with parameters: (1, 2) {}
        3
 
+
    dictionary
        Resembling a language dictionary, which provides a mapping between
        words and descriptions thereof, a Python dictionary is a mapping
@@ -149,48 +319,55 @@ Glossary
        For more information on dictionaries, read the
        `Python tutorial <https://docs.python.org/tutorial/>`_.
 
+
+   dimension
+
+       See :term:`axis`.
+
+
+   dtype
+
+       The datatype describing the (identically typed) elements in an ndarray.
+       It can be changed to reinterpret the array contents. For details, see
+       :doc:`Data type objects (dtype). <reference/arrays.dtypes>`
+
+
+   fancy indexing
+
+       Another term for :term:`advanced indexing`.
+
+
    field
        In a :term:`structured data type`, each sub-type is called a `field`.
        The `field` has a name (a string), a type (any valid dtype), and
        an optional `title`. See :ref:`arrays.dtypes`
 
+
    Fortran order
        See `column-major`
 
+
    flattened
        Collapsed to a one-dimensional array. See `numpy.ndarray.flatten`
        for details.
 
+
    homogeneous
-       Describes a block of memory comprised of blocks, each block comprised of 
+       Describes a block of memory comprised of blocks, each block comprised of
        items and of the same size, and blocks are interpreted in exactly the
        same way. In the simplest case each block contains a single item, for
        instance int32 or float64.
 
+
    immutable
        An object that cannot be modified after execution is called
        immutable.  Two common examples are strings and tuples.
 
-   iterable
-       A sequence that allows "walking" (iterating) over items, typically
-       using a loop such as::
-
-         >>> x = [1, 2, 3]
-         >>> [item**2 for item in x]
-         [1, 4, 9]
-
-       It is often used in combination with ``enumerate``::
-         >>> keys = ['a','b','c']
-         >>> for n, k in enumerate(keys):
-         ...     print("Key %d: %s" % (n, k))
-         ...
-         Key 0: a
-         Key 1: b
-         Key 2: c
 
    itemsize
        The size of the dtype element in bytes.
 
+
    list
        A Python container that can hold any number of objects or items.
        The items do not have to be of the same type, and can even be
@@ -223,12 +400,14 @@ Glossary
        tutorial <https://docs.python.org/tutorial/>`_.  For a mapping
        type (key-value), see *dictionary*.
 
+
    little-endian
        When storing a multi-byte value in memory as a sequence of bytes, the
        sequence addresses/sends/stores the least significant byte first (lowest
        address) and the most significant byte last (highest address). Common in
        x86 processors.
 
+
    mask
        A boolean array, used to select only certain elements for an operation::
 
@@ -244,6 +423,7 @@ Glossary
          >>> x
          array([ 0,  1,  2,  -1, -1])
 
+
    masked array
        Array that suppressed values indicated by a mask::
 
@@ -262,6 +442,7 @@ Glossary
        Masked arrays are often used when operating on arrays containing
        missing or invalid entries.
 
+
    matrix
        A 2-dimensional ndarray that preserves its two-dimensional nature
        throughout operations.  It has certain special operations, such as ``*``
@@ -276,18 +457,40 @@ Glossary
          matrix([[ 7, 10],
                [15, 22]])
 
+
    ndarray
        See *array*.
 
+
+   object array
+
+       An array whose dtype is ``object``; that is, it contains references to
+       Python objects. Indexing the array dereferences the Python objects, so
+       unlike other ndarrays, an object array has the ability to hold
+       heterogeneous objects.
+
+
+   ravel
+
+       `numpy.ravel` and `numpy.ndarray.flatten` both flatten an ndarray. ``ravel``
+       will return a view if possible; ``flatten`` always returns a copy.
+
+       Flattening collapses a multi-dimensional array to a single dimension;
+       details of how this is done (for instance, whether ``a[n+1]`` should be
+       the next row or next column) are parameters.
+
+
    record array
        An :term:`ndarray` with :term:`structured data type` which has been
        subclassed as ``np.recarray`` and whose dtype is of type ``np.record``,
        making the fields of its data type to be accessible by attribute.
 
+
    reference
        If ``a`` is a reference to ``b``, then ``(a is b) == True``.  Therefore,
        ``a`` and ``b`` are different names for the same Python object.
 
+
    row-major
        A way to represent items in a N-dimensional array in the 1-dimensional
        computer memory. In row-major order, the rightmost index "varies
@@ -303,6 +506,7 @@ Glossary
        Row-major order is also known as the C order, as the C programming
        language uses it. New NumPy arrays are by default in row-major order.
 
+
    slice
        Used to select only certain elements from a sequence:
 
@@ -330,9 +534,40 @@ Glossary
        >>> x[:, 1]
        array([2, 4])
 
+
+   stride
+
+       Physical memory is one-dimensional;  strides provide a mechanism to map
+       a given index to an address in memory. For an N-dimensional array, its
+       ``strides`` attribute is an N-element tuple; advancing from index
+       ``i`` to index ``i+1`` on axis ``n`` means adding ``a.strides[n]`` bytes
+       to the address.
+
+       Strides are computed automatically from an array's dtype and
+       shape, but can be directly specified using
+       :doc:`as_strided. <reference/generated/numpy.lib.stride_tricks.as_strided>`
+
+       For details, see
+       :doc:`numpy.ndarray.strides <reference/generated/numpy.ndarray.strides>`.
+
+       To see how striding underlies the power of NumPy views, see
+       `The NumPy array: a structure for efficient numerical computation. \
+       <https://arxiv.org/pdf/1102.1523.pdf>`_
+
+
+   structure
+       See :term:`structured data type`
+
+
+   structured array
+
+       Array whose :term:`dtype` is a :term:`structured data type`.
+
+
    structured data type
        A data type composed of other datatypes
 
+
    subarray data type
        A :term:`structured data type` may contain a :term:`ndarray` with its
        own dtype and shape:
@@ -342,16 +577,19 @@ Glossary
        array([(0, [0., 0., 0.]), (0, [0., 0., 0.]), (0, [0., 0., 0.])],
              dtype=[('a', '<i4'), ('b', '<f4', (3,))])
 
+
    title
        In addition to field names, structured array fields may have an
        associated :ref:`title <titles>` which is an alias to the name and is
        commonly used for plotting.
 
+
    ufunc
        Universal function.  A fast element-wise, :term:`vectorized
        <vectorization>` array operation.  Examples include ``add``, ``sin`` and
        ``logical_or``.
 
+
    vectorization
        Optimizing a looping block by specialized code. In a traditional sense,
        vectorization performs the same operation on multiple elements with
@@ -362,6 +600,7 @@ Glossary
        operations on multiple elements, typically achieving speedups by
        avoiding some of the overhead in looking up and converting the elements.
 
+
    view
        An array that does not own its data, but refers to another array's
        data instead.  For example, we may create a view that only shows
@@ -379,6 +618,7 @@ Glossary
          >>> y
          array([3, 2, 4])
 
+
    wrapper
        Python is a high-level (highly abstracted, or English-like) language.
        This abstraction comes at a price in execution speed, and sometimes
@@ -390,4 +630,3 @@ Glossary
        Examples include ctypes, SWIG and Cython (which wraps C and C++)
        and f2py (which wraps Fortran).
 
-
diff --git a/doc/source/reference/arrays.indexing.rst b/doc/source/reference/arrays.indexing.rst
index 3e600b7c4..180a79dae 100644
--- a/doc/source/reference/arrays.indexing.rst
+++ b/doc/source/reference/arrays.indexing.rst
@@ -198,6 +198,7 @@ concepts to remember include:
    create an axis of length one. :const:`newaxis` is an alias for
    'None', and 'None' can be used in place of this with the same result.
 
+.. _advanced-indexing:
 
 Advanced Indexing
 -----------------
@@ -304,6 +305,8 @@ understood with an example.
     most important thing to remember about indexing with multiple advanced
     indexes.
 
+.. _combining-advanced-and-basic-indexing:
+
 Combining advanced and basic indexing
 """""""""""""""""""""""""""""""""""""