DOC: enable docstring on DataFrame.columns/index (#20385)

Author: jorisvandenbossche

doc/source/api.rst

@@ -263,7 +263,11 @@ Constructor
 Attributes
 ~~~~~~~~~~
 **Axes**
- * **index**: axis labels
+
+.. autosummary::
+ :toctree: generated/
+
+ Series.index
 
 .. autosummary::
  :toctree: generated/
@@ -845,13 +849,15 @@ Attributes and underlying data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Axes**
 
- * **index**: row labels
- * **columns**: column labels
+.. autosummary::
+ :toctree: generated/
+
+ DataFrame.index
+ DataFrame.columns
 
 .. autosummary::
  :toctree: generated/
 
- DataFrame.as_matrix
  DataFrame.dtypes
  DataFrame.ftypes
  DataFrame.get_dtype_counts
@@ -2546,8 +2552,7 @@ objects.
  :hidden:
 
  generated/pandas.DataFrame.blocks
- generated/pandas.DataFrame.columns
- generated/pandas.DataFrame.index
+ generated/pandas.DataFrame.as_matrix
  generated/pandas.DataFrame.ix
  generated/pandas.Index.asi8
  generated/pandas.Index.data
@@ -2566,6 +2571,5 @@ objects.
  generated/pandas.Series.asobject
  generated/pandas.Series.blocks
  generated/pandas.Series.from_array
- generated/pandas.Series.index
  generated/pandas.Series.ix
  generated/pandas.Timestamp.offset

pandas/_libs/properties.pyx

@@ -42,19 +42,22 @@ cache_readonly = CachedProperty
 
 
 cdef class AxisProperty(object):
- cdef:
+
+ cdef readonly:
  Py_ssize_t axis
+ object __doc__
 
- def __init__(self, axis=0):
+ def __init__(self, axis=0, doc=""):
  self.axis = axis
+ self.__doc__ = doc
 
  def __get__(self, obj, type):
  cdef:
  list axes
 
  if obj is None:
  # Only instances have _data, not classes
- return None
+ return self
  else:
  axes = obj._data.axes
  return axes[self.axis]

pandas/core/frame.py

@@ -6989,7 +6989,10 @@ def isin(self, values):
 
 
 DataFrame._setup_axes(['index', 'columns'], info_axis=1, stat_axis=0,
- axes_are_reversed=True, aliases={'rows': 0})
+ axes_are_reversed=True, aliases={'rows': 0},
+ docs={
+ 'index': 'The index (row labels) of the DataFrame.',
+ 'columns': 'The column labels of the DataFrame.'})
 DataFrame._add_numeric_operations()
 DataFrame._add_series_or_dataframe_operations()
 

pandas/core/generic.py

@@ -236,7 +236,7 @@ def _constructor_expanddim(self):
  @classmethod
  def _setup_axes(cls, axes, info_axis=None, stat_axis=None, aliases=None,
  slicers=None, axes_are_reversed=False, build_axes=True,
- ns=None):
+ ns=None, docs=None):
  """Provide axes setup for the major PandasObjects.
 
  Parameters
@@ -278,7 +278,7 @@ def _setup_axes(cls, axes, info_axis=None, stat_axis=None, aliases=None,
  if build_axes:
 
  def set_axis(a, i):
- setattr(cls, a, properties.AxisProperty(i))
+ setattr(cls, a, properties.AxisProperty(i, docs.get(a, a)))
  cls._internal_names_set.add(a)
 
  if axes_are_reversed:

pandas/core/panel.py

@@ -1523,7 +1523,8 @@ def _extract_axis(self, data, axis=0, intersect=False):
  stat_axis=1, aliases={'major': 'major_axis',
  'minor': 'minor_axis'},
  slicers={'major_axis': 'index',
- 'minor_axis': 'columns'})
+ 'minor_axis': 'columns'},
+ docs={})
 
 ops.add_special_arithmetic_methods(Panel)
 ops.add_flex_arithmetic_methods(Panel)

pandas/core/series.py

@@ -3871,7 +3871,8 @@ def to_period(self, freq=None, copy=True):
  hist = gfx.hist_series
 
 
-Series._setup_axes(['index'], info_axis=0, stat_axis=0, aliases={'rows': 0})
+Series._setup_axes(['index'], info_axis=0, stat_axis=0, aliases={'rows': 0},
+ docs={'index': 'The index (axis labels) of the Series.'})
 Series._add_numeric_operations()
 Series._add_series_only_operations()
 Series._add_series_or_dataframe_operations()

pandas/tests/frame/test_api.py

@@ -6,6 +6,7 @@
 
 # pylint: disable-msg=W0612,E1101
 from copy import deepcopy
+import pydoc
 import sys
 from distutils.version import LooseVersion
 
@@ -362,8 +363,9 @@ def test_axis_aliases(self):
 
  def test_class_axis(self):
  # https://github.com/pandas-dev/pandas/issues/18147
- DataFrame.index # no exception!
- DataFrame.columns # no exception!
+ # no exception and no empty docstring
+ assert pydoc.getdoc(DataFrame.index)
+ assert pydoc.getdoc(DataFrame.columns)
 
  def test_more_values(self):
  values = self.mixed_frame.values

pandas/tests/series/test_api.py

@@ -1,6 +1,7 @@
 # coding=utf-8
 # pylint: disable-msg=E1101,W0612
 from collections import OrderedDict
+import pydoc
 
 import pytest
 
@@ -384,7 +385,8 @@ def test_axis_alias(self):
 
  def test_class_axis(self):
  # https://github.com/pandas-dev/pandas/issues/18147
- Series.index # no exception!
+ # no exception and no empty docstring
+ assert pydoc.getdoc(Series.index)
 
  def test_numpy_unique(self):
  # it works!