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/source/contributing.rst

@@ -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/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

@@ -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/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', # 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/core/categorical.py

@@ -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/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

@@ -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/datetimes.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/interval.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/multi.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):