DOC: document subclasses in API docs with selection of specific methods/attributes (#18202)

Removes our hack in the vendored numpydoc/numpydoc.py to exclude autosummary generation for certain methods. Instead, we'll explicitly list the relevant methods in a new Methods section in those docs. This let's us include things like IntervalIndex in the API docs, without having all the regular index methods in the table, and without auto-gen making pages for all of those.

Author: TomAugspurger

doc/source/api.rst

@@ -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/source/conf.py

@@ -317,6 +317,27 @@ Some other important things to know about the docs:
   doc build. This approach means that code examples will always be up to date,
   but it does make the doc building a bit more complex.
 
+- Our API documentation in ``doc/source/api.rst`` houses the auto-generated
+  documentation from the docstrings. For classes, there are a few subtleties
+  around controlling which methods and attributes have pages auto-generated.
+
+  We have two autosummary templates for classes.
+
+  1. ``_templates/autosummary/class.rst``. Use this when you want to
+     automatically generate a page for every public method and attribute on the
+     class. The ``Attributes`` and ``Methods`` sections will be automatically
+     added to the class' rendered documentation by numpydoc. See ``DataFrame``
+     for an example.
+
+  2. ``_templates/autosummary/class_without_autosummary``. Use this when you
+     want to pick a subset of methods / attributes to auto-generate pages for.
+     When using this template, you should include an ``Attributes`` and
+     ``Methods`` section in the class docstring. See ``CategoricalIndex`` for an
+     example.
+
+  Every method should be included in a ``toctree`` in ``api.rst``, else Sphinx
+  will emit a warning.
+
 .. note::
 
     The ``.rst`` files are used to automatically generate Markdown and HTML versions

doc/source/contributing.rst

@@ -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*'),

doc/sphinxext/numpydoc/numpydoc.py

@@ -282,6 +282,8 @@ class Timestamp(_Timestamp):
     @classmethod
     def fromordinal(cls, ordinal, freq=None, tz=None, offset=None):
         """
+        Timestamp.fromordinal(ordinal, 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
 
@@ -302,8 +304,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
         ----------
@@ -317,6 +321,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.
@@ -330,18 +336,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/tslib.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',  # noqa:E128
+        """
+        Timestamp.utcfromtimestamp(ts)
+
+        Construct a naive UTC datetime from a POSIX timestamp.
+        """
+    )
+    fromtimestamp = _make_error_func('fromtimestamp',  # noqa:E128
+        """
+        Timestamp.fromtimestamp(ts)
+
+        timestamp[, tz] -> tz's local time from POSIX timestamp.
+        """
+    )
+    combine = _make_error_func('combine',  # noqa:E128
+        """
+        Timsetamp.combine(date, time)
+
+        date, time -> datetime with same date and time fields
+        """
+    )
+    utcnow = _make_error_func('utcnow',  # noqa:E128
+        """
+        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(ordinal, 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/_libs/tslibs/nattype.pyx

@@ -194,6 +194,11 @@ class Categorical(PandasObject):
 
         .. versionadded:: 0.21.0
 
+    Methods
+    -------
+    from_codes
+    __array__
+
     Raises
     ------
     ValueError
@@ -401,7 +406,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/categorical.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/dtypes/dtypes.py

@@ -46,6 +46,24 @@ class CategoricalIndex(Index, accessor.PandasDelegate):
     name : object
         Name to be stored in the index
 
+    Attributes
+    ----------
+    codes
+    categories
+    ordered
+
+    Methods
+    -------
+    rename_categories
+    reorder_categories
+    add_categories
+    remove_categories
+    remove_unused_categories
+    set_categories
+    as_ordered
+    as_unordered
+    map
+
     See Also
     --------
     Categorical, Index

pandas/core/indexes/category.py

@@ -203,6 +203,54 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin,
     name : object
         Name to be stored in the index
 
+    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
+
+    Methods
+    -------
+    normalize
+    strftime
+    snap
+    tz_convert
+    tz_localize
+    round
+    floor
+    ceil
+    to_datetime
+    to_period
+    to_perioddelta
+    to_pydatetime
+    to_series
+    to_frame
+
     Notes
     -----
     To learn more about the frequency strings, please see `this link

pandas/core/indexes/datetimes.py

@@ -121,6 +121,17 @@ 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
+
+    Methods
+    -------
+    from_arrays
+    from_tuples
+    from_breaks
+    from_intervals
+    contains
 
     Examples
     ---------

pandas/core/indexes/interval.py

@@ -95,6 +95,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
@@ -1362,10 +1386,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)
 
     def __reduce__(self):