DOC: Overhaul the scalar type documentation to use `..autoclass`

This remove the tables. since they only had three columns, and using the character code is advised against anyway.

With this change, the individual scalar types as well as their aliases are now valid sphinx python domain targets.

1 files changed, 220 insertions, 99 deletions

diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst
index 46d2bb8fa..174dd2b91 100644
--- a/doc/source/reference/arrays.scalars.rst
+++ b/doc/source/reference/arrays.scalars.rst
@@ -41,6 +41,13 @@ of the flexible itemsize array types (:class:`string`,
    pointer for the platform. All the number types can be obtained
    using bit-width names as well.
 
+
+.. TODO - use something like this instead of the diagram above, as it generates
+   links to the classes and is a vector graphic. Unfortunately it looks worse
+   and the html <map> element providing the linked regions is misaligned.
+
+   .. inheritance-diagram:: byte short intc int_ longlong ubyte ushort uintc uint ulonglong half single double longdouble csingle cdouble clongdouble bool_ datetime64 timedelta64 object_ bytes_ str_ void
+
 .. [#] However, array scalars are immutable, so none of the array
        scalar attributes are settable.
 
@@ -51,14 +58,8 @@ of the flexible itemsize array types (:class:`string`,
 Built-in scalar types
 =====================
 
-The built-in scalar types are shown below. Along with their (mostly)
-C-derived names, the integer, float, and complex data-types are also
-available using a bit-width convention so that an array of the right
-size can always be ensured (e.g. :class:`int8`, :class:`float64`,
-:class:`complex128`). Two aliases (:class:`intp` and :class:`uintp`)
-pointing to the integer type that is sufficiently large to hold a C pointer
-are also provided. The C-like names are associated with character codes,
-which are shown in the table. Use of the character codes, however,
+The built-in scalar types are shown below. The C-like names are associated with character codes,
+which are shown in their descriptions. Use of the character codes, however,
 is discouraged.
 
 Some of the scalar types are essentially equivalent to fundamental
@@ -86,97 +87,119 @@ Python Boolean scalar.
 
 .. warning::
 
-   The :class:`bool_` type is not a subclass of the :class:`int_` type
-   (the :class:`bool_` is not even a number type). This is different
-   than Python's default implementation of :class:`bool` as a
-   sub-class of :class:`int`.
-
-.. warning::
-
    The :class:`int_` type does **not** inherit from the
    :class:`int` built-in under Python 3, because type :class:`int` is no
    longer a fixed-width integer type.
 
 .. tip:: The default data type in NumPy is :class:`float_`.
 
-In the tables below, ``platform?`` means that the type may not be
-available on all platforms. Compatibility with different C or Python
-types is indicated: two types are compatible if their data is of the
-same size and interpreted in the same way.
-
-Booleans:
-
-===================  =============================  ===============
-Type                 Remarks                        Character code
-===================  =============================  ===============
-:class:`bool_`       compatible: Python bool        ``'?'``
-:class:`bool8`       8 bits
-===================  =============================  ===============
-
-Integers:
-
-===================  =============================  ===============
-:class:`byte`        compatible: C ``char``         ``'b'``
-:class:`short`       compatible: C ``short``        ``'h'``
-:class:`intc`        compatible: C ``int``          ``'i'``
-:class:`int_`        compatible: C ``long``         ``'l'``
-:class:`longlong`    compatible: C ``long long``    ``'q'``
-:class:`intp`        large enough to fit a pointer  ``'p'``
-:class:`int8`        8 bits
-:class:`int16`       16 bits
-:class:`int32`       32 bits
-:class:`int64`       64 bits
-===================  =============================  ===============
-
-Unsigned integers:
-
-===================  =================================  ===============
-:class:`ubyte`       compatible: C ``unsigned char``    ``'B'``
-:class:`ushort`      compatible: C ``unsigned short``   ``'H'``
-:class:`uintc`       compatible: C ``unsigned int``     ``'I'``
-:class:`uint`        compatible: C ``long``             ``'L'``
-:class:`ulonglong`   compatible: C ``long long``        ``'Q'``
-:class:`uintp`       large enough to fit a pointer      ``'P'``
-:class:`uint8`       8 bits
-:class:`uint16`      16 bits
-:class:`uint32`      32 bits
-:class:`uint64`      64 bits
-===================  =================================  ===============
-
-Floating-point numbers:
-
-===================  =============================  ===============
-:class:`half`                                       ``'e'``
-:class:`single`      compatible: C float            ``'f'``
-:class:`double`      compatible: C double
-:class:`float_`      compatible: Python float       ``'d'``
-:class:`longfloat`   compatible: C long float       ``'g'``
-:class:`float16`     16 bits
-:class:`float32`     32 bits
-:class:`float64`     64 bits
-:class:`float96`     96 bits, platform?
-:class:`float128`    128 bits, platform?
-===================  =============================  ===============
-
-Complex floating-point numbers:
-
-===================  =============================  ===============
-:class:`csingle`                                    ``'F'``
-:class:`complex_`    compatible: Python complex     ``'D'``
-:class:`clongfloat`                                 ``'G'``
-:class:`complex64`   two 32-bit floats
-:class:`complex128`  two 64-bit floats
-:class:`complex192`  two 96-bit floats,
-                     platform?
-:class:`complex256`  two 128-bit floats,
-                     platform?
-===================  =============================  ===============
-
-Any Python object:
-
-===================  =============================  ===============
-:class:`object_`     any Python object              ``'O'``
-===================  =============================  ===============
+.. autoclass:: numpy.generic
+   :exclude-members:
+
+.. autoclass:: numpy.number
+   :exclude-members:
+
+Integer types
+~~~~~~~~~~~~~
+
+.. autoclass:: numpy.integer
+   :exclude-members:
+
+Signed integer types
+++++++++++++++++++++
+
+.. autoclass:: numpy.signedinteger
+   :exclude-members:
+
+.. autoclass:: numpy.byte
+   :exclude-members:
+
+.. autoclass:: numpy.short
+   :exclude-members:
+
+.. autoclass:: numpy.intc
+   :exclude-members:
+
+.. autoclass:: numpy.int_
+   :exclude-members:
+
+.. autoclass:: numpy.longlong
+   :exclude-members:
+
+Unsigned integer types
+++++++++++++++++++++++
+
+.. autoclass:: numpy.unsignedinteger
+   :exclude-members:
+
+.. autoclass:: numpy.ubyte
+   :exclude-members:
+
+.. autoclass:: numpy.ushort
+   :exclude-members:
+
+.. autoclass:: numpy.uintc
+   :exclude-members:
+
+.. autoclass:: numpy.uint
+   :exclude-members:
+
+.. autoclass:: numpy.ulonglong
+   :exclude-members:
+
+Inexact types
+~~~~~~~~~~~~~
+
+.. autoclass:: numpy.inexact
+   :exclude-members:
+
+Floating-point types
+++++++++++++++++++++
+
+.. autoclass:: numpy.floating
+   :exclude-members:
+
+.. autoclass:: numpy.half
+   :exclude-members:
+
+.. autoclass:: numpy.single
+   :exclude-members:
+
+.. autoclass:: numpy.double
+   :exclude-members:
+
+.. autoclass:: numpy.longdouble
+   :exclude-members:
+
+Complex floating-point types
+++++++++++++++++++++++++++++
+
+.. autoclass:: numpy.complexfloating
+   :exclude-members:
+
+.. autoclass:: numpy.csingle
+   :exclude-members:
+
+.. autoclass:: numpy.cdouble
+   :exclude-members:
+
+.. autoclass:: numpy.clongdouble
+   :exclude-members:
+
+Other types
+~~~~~~~~~~~
+
+.. autoclass:: numpy.bool_
+   :exclude-members:
+
+.. autoclass:: numpy.datetime64
+   :exclude-members:
+
+.. autoclass:: numpy.timedelta64
+   :exclude-members:
+
+.. autoclass:: numpy.object_
+   :exclude-members:
 
 .. note::
 
@@ -198,11 +221,17 @@ size and the data they describe can be of different length in different
 arrays. (In the character codes ``#`` is an integer denoting how many
 elements the data type consists of.)
 
-===================  ==============================  ========
-:class:`bytes_`      compatible: Python bytes        ``'S#'``
-:class:`unicode_`    compatible: Python unicode/str  ``'U#'``
-:class:`void`                                        ``'V#'``
-===================  ==============================  ========
+.. autoclass:: numpy.flexible
+   :exclude-members:
+
+.. autoclass:: numpy.bytes_
+   :exclude-members:
+
+.. autoclass:: numpy.str_
+   :exclude-members:
+
+.. autoclass:: numpy.void
+   :exclude-members:
 
 
 .. warning::
@@ -217,6 +246,99 @@ elements the data type consists of.)
    convention more consistent with other Python modules such as the
    :mod:`struct` module.
 
+Sized aliases
+~~~~~~~~~~~~~
+
+Along with their (mostly)
+C-derived names, the integer, float, and complex data-types are also
+available using a bit-width convention so that an array of the right
+size can always be ensured. Two aliases (:class:`numpy.intp` and :class:`numpy.uintp`)
+pointing to the integer type that is sufficiently large to hold a C pointer
+are also provided.
+
+.. note that these are documented with ..attribute because that is what
+   autoclass does for aliases under the hood.
+
+.. autoclass:: numpy.bool8
+
+.. attribute:: numpy.int8
+               numpy.int16
+               numpy.int32
+               numpy.int64
+
+   Aliases for the signed integer types (one of `numpy.byte`, `numpy.short`,
+   `numpy.intc`, `numpy.int_` and `numpy.longlong`) with the specified number
+   of bits.
+
+   Compatible with the C99 ``int8_t``, ``int16_t``, ``int32_t``, and
+   ``int64_t``, respectively.
+
+.. attribute:: numpy.uint8
+               numpy.uint16
+               numpy.uint32
+               numpy.uint64
+
+   Alias for the unsigned integer types (one of `numpy.byte`, `numpy.short`,
+   `numpy.intc`, `numpy.int_` and `numpy.longlong`) with the specified number
+   of bits.
+
+   Compatible with the C99 ``uint8_t``, ``uint16_t``, ``uint32_t``, and
+   ``uint64_t``, respectively.
+
+.. attribute:: numpy.intp
+
+   Alias for the signed integer type (one of `numpy.byte`, `numpy.short`,
+   `numpy.intc`, `numpy.int_` and `np.longlong`) that is the same size as a
+   pointer.
+
+   Compatible with the C ``intptr_t``.
+
+   :Character code: ``'p'``
+
+.. attribute:: numpy.uintp
+
+   Alias for the unsigned integer type (one of `numpy.byte`, `numpy.short`,
+   `numpy.intc`, `numpy.int_` and `np.longlong`) that is the same size as a
+   pointer.
+
+   Compatible with the C ``uintptr_t``.
+
+   :Character code: ``'P'``
+
+.. autoclass:: numpy.float16
+
+.. autoclass:: numpy.float32
+
+.. autoclass:: numpy.float64
+
+.. attribute:: numpy.float96
+               numpy.float128
+
+   Alias for `numpy.longdouble`, named after its size in bits.
+   The existance of these aliases depends on the platform.
+
+.. autoclass:: numpy.complex64
+
+.. autoclass:: numpy.complex128
+
+.. attribute:: numpy.complex192
+               numpy.complex256
+
+   Alias for `numpy.clongdouble`, named after its size in bits.
+   The existance of these aliases depends on the platform.
+
+Other aliases
+~~~~~~~~~~~~~
+
+.. autoclass:: float_
+
+.. autoclass:: complex_
+
+.. autoclass:: longfloat
+
+.. autoclass:: clongfloat
+
+.. autoclass:: longcomplex
 
 Attributes
 ==========
@@ -276,7 +398,6 @@ The exceptions to the above rules are given below:
 .. autosummary::
    :toctree: generated/
 
-   generic
    generic.__array__
    generic.__array_wrap__
    generic.squeeze