DOC: better document Dtypes docstrings + avoid sphinx warnings (#26067)

Author: jorisvandenbossche

doc/source/reference/arrays.rst

@@ -146,6 +146,11 @@ If the data are tz-aware, then every value in the array must have the same timez
    :toctree: api/
 
    arrays.DatetimeArray
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
+
    DatetimeTZDtype
 
 .. _api.arrays.timedelta:
@@ -260,6 +265,11 @@ Every period in a ``PeriodArray`` must have the same ``freq``.
    :toctree: api/
 
    arrays.PeriodArray
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
+
    PeriodDtype
 
 .. _api.arrays.interval:
@@ -296,6 +306,11 @@ A collection of intervals may be stored in an :class:`arrays.IntervalArray`.
    :toctree: api/
 
    arrays.IntervalArray
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
+
    IntervalDtype
 
 .. _api.arrays.integer_na:
@@ -310,6 +325,11 @@ Pandas provides this through :class:`arrays.IntegerArray`.
    :toctree: api/
 
    arrays.IntegerArray
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
+
    Int8Dtype
    Int16Dtype
    Int32Dtype
@@ -396,8 +416,27 @@ be stored efficiently as a :class:`SparseArray`.
    :toctree: api/
 
    SparseArray
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/class_without_autosummary.rst
+
    SparseDtype
 
 The ``Series.sparse`` accessor may be used to access sparse-specific attributes
 and methods if the :class:`Series` contains sparse values. See
 :ref:`api.series.sparse` for more.
+
+
+
+.. Dtype attributes which are manually listed in their docstrings: including
+.. it here to make sure a docstring page is built for them
+
+..
+    .. autosummary::
+      :toctree: api/
+
+      DatetimeTZDtype.unit
+      DatetimeTZDtype.tz
+      PeriodDtype.freq
+      IntervalDtype.subtype

pandas/core/arrays/integer.py

@@ -682,6 +682,17 @@ def integer_arithmetic_method(self, other):
 
 module = sys.modules[__name__]
 
+_dtype_docstring = """
+An ExtensionDtype for {dtype} integer data.
+
+Attributes
+----------
+None
+
+Methods
+-------
+None
+"""
 
 # create the Dtype
 _dtypes = {}
@@ -695,7 +706,8 @@ def integer_arithmetic_method(self, other):
     classname = "{}Dtype".format(name)
     numpy_dtype = getattr(np, dtype)
     attributes_dict = {'type': numpy_dtype,
-                       'name': name}
+                       'name': name,
+                       '__doc__': _dtype_docstring.format(dtype=dtype)}
     dtype_type = register_extension_dtype(
         type(classname, (_IntegerDtype, ), attributes_dict)
     )

pandas/core/arrays/sparse.py

@@ -72,6 +72,14 @@ class SparseDtype(ExtensionDtype):
         =========== ==========
 
         The default value may be overridden by specifying a `fill_value`.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
     """
     # We include `_is_na_fill_value` in the metadata to avoid hash collisions
     # between SparseDtype(float, 0.0) and SparseDtype(float, nan).

pandas/core/dtypes/dtypes.py

@@ -169,7 +169,7 @@ class CategoricalDtypeType(type):
 @register_extension_dtype
 class CategoricalDtype(PandasExtensionDtype, ExtensionDtype):
     """
-    Type for categorical data with the categories and orderedness
+    Type for categorical data with the categories and orderedness.
 
     .. versionchanged:: 0.21.0
 
@@ -334,6 +334,9 @@ def _finalize(self, categories, ordered, fastpath=False):
         self._ordered = ordered
 
     def __setstate__(self, state):
+        # for pickle compat. __get_state__ is defined in the
+        # PandasExtensionDtype superclass and uses the public properties to
+        # pickle -> need to set the settable private ones here (see GH26067)
         self._categories = state.pop('categories', None)
         self._ordered = state.pop('ordered', False)
 
@@ -570,13 +573,40 @@ def _is_boolean(self):
 
 @register_extension_dtype
 class DatetimeTZDtype(PandasExtensionDtype, ExtensionDtype):
-
     """
-    A np.dtype duck-typed class, suitable for holding a custom datetime with tz
-    dtype.
+    An ExtensionDtype for timezone-aware datetime data.
+
+    **This is not an actual numpy dtype**, but a duck type.
+
+    Parameters
+    ----------
+    unit : str, default "ns"
+        The precision of the datetime data. Currently limited
+        to ``"ns"``.
+    tz : str, int, or datetime.tzinfo
+        The timezone.
+
+    Attributes
+    ----------
+    unit
+    tz
+
+    Methods
+    -------
+    None
 
-    THIS IS NOT A REAL NUMPY DTYPE, but essentially a sub-class of
-    np.datetime64[ns]
+    Raises
+    ------
+    pytz.UnknownTimeZoneError
+        When the requested timezone cannot be found.
+
+    Examples
+    --------
+    >>> pd.DatetimeTZDtype(tz='UTC')
+    datetime64[ns, UTC]
+
+    >>> pd.DatetimeTZDtype(tz='dateutil/US/Central')
+    datetime64[ns, tzfile('/usr/share/zoneinfo/US/Central')]
     """
     type = Timestamp  # type: Type[Timestamp]
     kind = 'M'  # type: str_type
@@ -589,30 +619,6 @@ class DatetimeTZDtype(PandasExtensionDtype, ExtensionDtype):
     _cache = {}  # type: Dict[str_type, PandasExtensionDtype]
 
     def __init__(self, unit="ns", tz=None):
-        """
-        An ExtensionDtype for timezone-aware datetime data.
-
-        Parameters
-        ----------
-        unit : str, default "ns"
-            The precision of the datetime data. Currently limited
-            to ``"ns"``.
-        tz : str, int, or datetime.tzinfo
-            The timezone.
-
-        Raises
-        ------
-        pytz.UnknownTimeZoneError
-            When the requested timezone cannot be found.
-
-        Examples
-        --------
-        >>> pd.core.dtypes.dtypes.DatetimeTZDtype(tz='UTC')
-        datetime64[ns, UTC]
-
-        >>> pd.core.dtypes.dtypes.DatetimeTZDtype(tz='dateutil/US/Central')
-        datetime64[ns, tzfile('/usr/share/zoneinfo/US/Central')]
-        """
         if isinstance(unit, DatetimeTZDtype):
             unit, tz = unit.unit, unit.tz
 
@@ -718,17 +724,40 @@ def __eq__(self, other):
                 str(self.tz) == str(other.tz))
 
     def __setstate__(self, state):
-        # for pickle compat.
+        # for pickle compat. __get_state__ is defined in the
+        # PandasExtensionDtype superclass and uses the public properties to
+        # pickle -> need to set the settable private ones here (see GH26067)
         self._tz = state['tz']
         self._unit = state['unit']
 
 
 @register_extension_dtype
 class PeriodDtype(ExtensionDtype, PandasExtensionDtype):
     """
-    A Period duck-typed class, suitable for holding a period with freq dtype.
+    An ExtensionDtype for Period data.
+
+    **This is not an actual numpy dtype**, but a duck type.
+
+    Parameters
+    ----------
+    freq : str or DateOffset
+        The frequency of this PeriodDtype
+
+    Attributes
+    ----------
+    freq
 
-    THIS IS NOT A REAL NUMPY DTYPE, but essentially a sub-class of np.int64.
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.PeriodDtype(freq='D')
+    period[D]
+
+    >>> pd.PeriodDtype(freq=pd.offsets.MonthEnd())
+    period[M]
     """
     type = Period  # type: Type[Period]
     kind = 'O'  # type: str_type
@@ -751,7 +780,9 @@ def __new__(cls, freq=None):
 
         elif freq is None:
             # empty constructor for pickle compat
-            return object.__new__(cls)
+            u = object.__new__(cls)
+            u._freq = None
+            return u
 
         if not isinstance(freq, ABCDateOffset):
             freq = cls._parse_dtype_strict(freq)
@@ -760,10 +791,15 @@ def __new__(cls, freq=None):
             return cls._cache[freq.freqstr]
         except KeyError:
             u = object.__new__(cls)
-            u.freq = freq
+            u._freq = freq
             cls._cache[freq.freqstr] = u
             return u
 
+    @property
+    def freq(self):
+        """The frequency object of this PeriodDtype."""
+        return self._freq
+
     @classmethod
     def _parse_dtype_strict(cls, freq):
         if isinstance(freq, str):
@@ -817,6 +853,12 @@ def __eq__(self, other):
 
         return isinstance(other, PeriodDtype) and self.freq == other.freq
 
+    def __setstate__(self, state):
+        # for pickle compat. __get_state__ is defined in the
+        # PandasExtensionDtype superclass and uses the public properties to
+        # pickle -> need to set the settable private ones here (see GH26067)
+        self._freq = state['freq']
+
     @classmethod
     def is_dtype(cls, dtype):
         """
@@ -849,9 +891,27 @@ def construct_array_type(cls):
 @register_extension_dtype
 class IntervalDtype(PandasExtensionDtype, ExtensionDtype):
     """
-    A Interval duck-typed class, suitable for holding an interval
+    An ExtensionDtype for Interval data.
 
-    THIS IS NOT A REAL NUMPY DTYPE
+    **This is not an actual numpy dtype**, but a duck type.
+
+    Parameters
+    ----------
+    subtype : str, np.dtype
+        The dtype of the Interval bounds.
+
+    Attributes
+    ----------
+    subtype
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.IntervalDtype(subtype='int64')
+    interval[int64]
     """
     name = 'interval'
     kind = None  # type: Optional[str_type]
@@ -863,11 +923,6 @@ class IntervalDtype(PandasExtensionDtype, ExtensionDtype):
     _cache = {}  # type: Dict[str_type, PandasExtensionDtype]
 
     def __new__(cls, subtype=None):
-        """
-        Parameters
-        ----------
-        subtype : the dtype of the Interval
-        """
         from pandas.core.dtypes.common import (
             is_categorical_dtype, is_string_dtype, pandas_dtype)
 
@@ -877,7 +932,7 @@ def __new__(cls, subtype=None):
             # we are called as an empty constructor
             # generally for pickle compat
             u = object.__new__(cls)
-            u.subtype = None
+            u._subtype = None
             return u
         elif (isinstance(subtype, str) and
               subtype.lower() == 'interval'):
@@ -903,10 +958,15 @@ def __new__(cls, subtype=None):
             return cls._cache[str(subtype)]
         except KeyError:
             u = object.__new__(cls)
-            u.subtype = subtype
+            u._subtype = subtype
             cls._cache[str(subtype)] = u
             return u
 
+    @property
+    def subtype(self):
+        """The dtype of the Interval bounds."""
+        return self._subtype
+
     @classmethod
     def construct_array_type(cls):
         """
@@ -963,6 +1023,12 @@ def __eq__(self, other):
             from pandas.core.dtypes.common import is_dtype_equal
             return is_dtype_equal(self.subtype, other.subtype)
 
+    def __setstate__(self, state):
+        # for pickle compat. __get_state__ is defined in the
+        # PandasExtensionDtype superclass and uses the public properties to
+        # pickle -> need to set the settable private ones here (see GH26067)
+        self._subtype = state['subtype']
+
     @classmethod
     def is_dtype(cls, dtype):
         """