DOC: document subclasses in API docs with selection of specific methods/attributes

doc/source/conf.py

@@ -55,7 +55,7 @@
               'sphinx.ext.doctest',
               'sphinx.ext.extlinks',
               'sphinx.ext.todo',
-              'numpydoc', # used to parse numpy-style docstrings for autodoc
+              'numpydoc',
               'IPython.sphinxext.ipython_directive',
               'IPython.sphinxext.ipython_console_highlighting',
               'sphinx.ext.intersphinx',

doc/sphinxext/numpydoc/numpydoc.py

@@ -42,13 +42,6 @@ def mangle_docstrings(app, what, name, obj, options, lines,
                class_members_toctree=app.config.numpydoc_class_members_toctree,
               )
 
-    # PANDAS HACK (to remove the list of methods/attributes for Categorical)
-    no_autosummary = [".Categorical", "CategoricalIndex", "IntervalIndex",
-                      "RangeIndex", "Int64Index", "UInt64Index",
-                      "Float64Index", "PeriodIndex", "CategoricalDtype"]
-    if what == "class" and any(name.endswith(n) for n in no_autosummary):
-        cfg['class_members_list'] = False
-
     if what == 'module':
         # Strip top title
         title_re = re.compile(sixu('^\\s*[#*=]{4,}\\n[a-z0-9 -]+\\n[#*=]{4,}\\s*'),

pandas/_libs/tslib.pyx

@@ -288,6 +288,8 @@ class Timestamp(_Timestamp):
     @classmethod
     def fromordinal(cls, ordinal, freq=None, tz=None, offset=None):
         """
+        Timestamp.fromordinal(ordina, freq=None, tz=None, offset=None)
+
         passed an ordinal, translate and convert to a ts
         note: by definition there cannot be any tz info on the ordinal itself
 
@@ -308,8 +310,10 @@ class Timestamp(_Timestamp):
     @classmethod
     def now(cls, tz=None):
         """
-        Return the current time in the local timezone.  Equivalent
-        to datetime.now([tz])
+        Timestamp.now(tz=None)
+
+        Returns new Timestamp object representing current time local to
+        tz.
 
         Parameters
         ----------
@@ -323,6 +327,8 @@ class Timestamp(_Timestamp):
     @classmethod
     def today(cls, tz=None):
         """
+        Timestamp.today(cls, tz=None)
+
         Return the current time in the local timezone.  This differs
         from datetime.today() in that it can be localized to a
         passed timezone.
@@ -336,18 +342,38 @@ class Timestamp(_Timestamp):
 
     @classmethod
     def utcnow(cls):
+        """
+        Timestamp.utcnow()
+
+        Return a new Timestamp representing UTC day and time.
+        """
         return cls.now('UTC')
 
     @classmethod
     def utcfromtimestamp(cls, ts):
+        """
+        Timestamp.utcfromtimestamp(ts)
+
+        Construct a naive UTC datetime from a POSIX timestamp.
+        """
         return cls(datetime.utcfromtimestamp(ts))
 
     @classmethod
     def fromtimestamp(cls, ts):
+        """
+        Timestamp.fromtimestamp(ts)
+
+        timestamp[, tz] -> tz's local time from POSIX timestamp.
+        """
         return cls(datetime.fromtimestamp(ts))
 
     @classmethod
     def combine(cls, date, time):
+        """
+        Timsetamp.combine(date, time)
+
+        date, time -> datetime with same date and time fields
+        """
         return cls(datetime.combine(date, time))
 
     def __new__(cls, object ts_input=_no_input,

pandas/_libs/tslibs/nattype.pyx

@@ -336,16 +336,39 @@ class NaTType(_NaT):
     tzname = _make_error_func('tzname', datetime)
     utcoffset = _make_error_func('utcoffset', datetime)
 
-    # Timestamp has empty docstring for some methods.
-    utcfromtimestamp = _make_error_func('utcfromtimestamp', None)
-    fromtimestamp = _make_error_func('fromtimestamp', None)
-    combine = _make_error_func('combine', None)
-    utcnow = _make_error_func('utcnow', None)
-
     # ----------------------------------------------------------------------
     # The remaining methods have docstrings copy/pasted from the analogous
     # Timestamp methods.
 
+    utcfromtimestamp = _make_error_func('utcfromtimestamp',
+        """
+        Timestamp.utcfromtimestamp(ts)
+
+        Construct a naive UTC datetime from a POSIX timestamp.
+        """
+    )
+    fromtimestamp = _make_error_func('fromtimestamp',
+        """
+        Timestamp.fromtimestamp(ts)
+
+        timestamp[, tz] -> tz's local time from POSIX timestamp.
+        """
+    )
+    combine = _make_error_func('combine',
+        """
+        Timsetamp.combine(date, time)
+
+        date, time -> datetime with same date and time fields
+        """
+    )
+    utcnow = _make_error_func('utcnow',
+        """
+        Timestamp.utcnow()
+
+        Return a new Timestamp representing UTC day and time.
+        """
+    )
+
     timestamp = _make_error_func('timestamp',  # noqa:E128
         """Return POSIX timestamp as float.""")
 
@@ -372,6 +395,8 @@ class NaTType(_NaT):
         """)
     fromordinal = _make_error_func('fromordinal',  # noqa:E128
         """
+        Timestamp.fromordinal(ordina, freq=None, tz=None, offset=None)
+
         passed an ordinal, translate and convert to a ts
         note: by definition there cannot be any tz info on the ordinal itself
 
@@ -397,8 +422,10 @@ class NaTType(_NaT):
 
     now = _make_nat_func('now',  # noqa:E128
         """
-        Return the current time in the local timezone.  Equivalent
-        to datetime.now([tz])
+        Timestamp.now(tz=None)
+
+        Returns new Timestamp object representing current time local to
+        tz.
 
         Parameters
         ----------
@@ -407,6 +434,8 @@ class NaTType(_NaT):
         """)
     today = _make_nat_func('today',  # noqa:E128
         """
+        Timestamp.today(cls, tz=None)
+
         Return the current time in the local timezone.  This differs
         from datetime.today() in that it can be localized to a
         passed timezone.

pandas/core/categorical.py

@@ -430,7 +430,7 @@ def ordered(self):
 
     @property
     def dtype(self):
-        """The :ref:`~pandas.api.types.CategoricalDtype` for this instance"""
+        """The :class:`~pandas.api.types.CategoricalDtype` for this instance"""
         return self._dtype
 
     @property

pandas/core/dtypes/dtypes.py

@@ -120,6 +120,15 @@ class CategoricalDtype(ExtensionDtype):
         Must be unique, and must not contain any nulls.
     ordered : bool, default False
 
+    Attributes
+    ----------
+    categories
+    ordered
+
+    Methods
+    -------
+    None
+
     Notes
     -----
     This class is useful for specifying the type of a ``Categorical``

pandas/core/indexes/category.py

@@ -49,6 +49,25 @@ class CategoricalIndex(Index, accessor.PandasDelegate):
     See Also
     --------
     Categorical, Index
+
+    Methods
+    -------
+    rename_categories
+    reorder_categories
+    add_categories
+    remove_categories
+    remove_unused_categories
+    set_categories
+    as_ordered
+    as_unordered
+    get_loc
+    map
+
+    Attributes
+    ----------
+    codes
+    categories
+    ordered
     """
 
     _typ = 'categoricalindex'

pandas/core/indexes/datetimes.py

@@ -214,6 +214,54 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin,
     Index : The base pandas Index type
     TimedeltaIndex : Index of timedelta64 data
     PeriodIndex : Index of Period data
+
+    Methods
+    -------
+    normalize
+    strftime
+    snap
+    tz_convert
+    tz_localize
+    round
+    floor
+    ceil
+    to_datetime
+    to_period
+    to_perioddelta
+    to_pydatetime
+    to_series
+    to_frame
+
+    Attributes
+    ----------
+    year
+    month
+    day
+    hour
+    minute
+    second
+    microsecond
+    nanosecond
+    date
+    time
+    dayofyear
+    weekofyear
+    week
+    dayofweek
+    weekday
+    weekday_name
+    quarter
+    tz
+    freq
+    freqstr
+    is_month_start
+    is_month_end
+    is_quarter_start
+    is_quarter_end
+    is_year_start
+    is_year_end
+    is_leap_year
+    inferred_freq
     """
 
     _typ = 'datetimeindex'

pandas/core/indexes/interval.py

@@ -121,6 +121,9 @@ class IntervalIndex(IntervalMixin, Index):
         Name to be stored in the index.
     copy : boolean, default False
         Copy the meta-data
+    mid
+    values
+    is_non_overlapping_monotonic
 
     Examples
     ---------
@@ -154,6 +157,16 @@ class IntervalIndex(IntervalMixin, Index):
     IntervalIndex.from_intervals, IntervalIndex.from_tuples
     cut, qcut : convert arrays of continuous data into categoricals/series of
                 ``Interval``.
+
+    Methods
+    -------
+    from_arrays
+    from_tuples
+    from_breaks
+    from_intervals
+    contains
+    get_loc
+
     """
     _typ = 'intervalindex'
     _comparables = ['name']

pandas/core/indexes/multi.py

@@ -97,6 +97,30 @@ class MultiIndex(Index):
                               of iterables
     MultiIndex.from_tuples  : Convert list of tuples to a MultiIndex
     Index : The base pandas Index type
+
+    Attributes
+    ----------
+    names
+    levels
+    labels
+    nlevels
+    levshape
+
+    Methods
+    -------
+    from_arrays
+    from_tuples
+    from_product
+    set_levels
+    set_labels
+    to_hierarchical
+    to_frame
+    is_lexsorted
+    sortlevel
+    droplevel
+    swaplevel
+    reorder_levels
+    remove_unused_levels
     """
 
     # initialize to zero-length tuples to make everything work
@@ -1364,10 +1388,12 @@ def remove_unused_levels(self):
 
     @property
     def nlevels(self):
+        """Integer number of levels in this MultiIndex."""
         return len(self.levels)
 
     @property
     def levshape(self):
+        """A tuple with the length of each level."""
         return tuple(len(x) for x in self.levels)
 
     @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs)

pandas/core/indexes/numeric.py

@@ -122,6 +122,14 @@ def is_all_dates(self):
     name : object
         Name to be stored in the index
 
+    Attributes
+    ----------
+    inferred_type
+
+    Methods
+    -------
+    None
+
     Notes
     -----
     An Index instance can **only** contain hashable objects.
@@ -154,6 +162,7 @@ class Int64Index(NumericIndex):
 
     @property
     def inferred_type(self):
+        """Always 'integer' for ``Int64Index``"""
         return 'integer'
 
     @property
@@ -213,6 +222,7 @@ class UInt64Index(NumericIndex):
 
     @property
     def inferred_type(self):
+        """Always 'integer' for ``UInt64Index``"""
         return 'integer'
 
     @property
@@ -290,6 +300,7 @@ class Float64Index(NumericIndex):
 
     @property
     def inferred_type(self):
+        """Always 'floating' for ``Float64Index"""
         return 'floating'
 
     @Appender(_index_shared_docs['astype'])