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

mcrot · Mar 22, 2018 · 8f9ffcc · 8f9ffcc
1 parent 86684ad
commit 8f9ffcc
Show file tree

Hide file tree

Showing 8 changed files with 34 additions and 18 deletions.
diff --git a/doc/source/api.rst b/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
diff --git a/pandas/_libs/properties.pyx b/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]

diff --git a/pandas/core/frame.py b/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()
 

diff --git a/pandas/core/generic.py b/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:

diff --git a/pandas/core/panel.py b/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)

diff --git a/pandas/core/series.py b/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()

diff --git a/pandas/tests/frame/test_api.py b/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

diff --git a/pandas/tests/series/test_api.py b/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!