Merge pull request #5160 from jorisvandenbossche/api-docs-template

DOC: add DataFrame et al class docstring to api docs

Author: jreback

doc/source/_templates/autosummary/class.rst

@@ -0,0 +1,33 @@
+{% extends "!autosummary/class.rst" %}
+
+{% block methods %}
+{% if methods %}
+
+.. 
+   HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+   .. autosummary::
+      :toctree:
+      {% for item in all_methods %}
+      {%- if not item.startswith('_') or item in ['__call__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+      {%- endfor %}
+
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+
+..
+   HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+   .. autosummary::
+      :toctree:
+      {% for item in all_attributes %}
+      {%- if not item.startswith('_') %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+      {%- endfor %}
+
+{% endif %}
+{% endblock %}

doc/source/api.rst

@@ -206,6 +206,13 @@ Exponentially-weighted moving window functions
 Series
 ------
 
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+   :toctree: generated/
+
+   Series
+
 Attributes and underlying data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Axes**
@@ -219,13 +226,11 @@ Attributes and underlying data
    Series.isnull
    Series.notnull
 
-Conversion / Constructors
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
+Conversion
+~~~~~~~~~~
 .. autosummary::
    :toctree: generated/
 
-   Series.__init__
    Series.astype
    Series.copy
    Series.isnull
@@ -418,6 +423,13 @@ Serialization / IO / Conversion
 DataFrame
 ---------
 
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+   :toctree: generated/
+
+   DataFrame
+
 Attributes and underlying data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Axes**
@@ -436,12 +448,11 @@ Attributes and underlying data
    DataFrame.ndim
    DataFrame.shape
 
-Conversion / Constructors
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Conversion
+~~~~~~~~~~
 .. autosummary::
    :toctree: generated/
 
-   DataFrame.__init__
    DataFrame.astype
    DataFrame.convert_objects
    DataFrame.copy
@@ -665,6 +676,13 @@ Serialization / IO / Conversion
 Panel
 ------
 
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+   :toctree: generated/
+
+   Panel
+
 Attributes and underlying data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Axes**
@@ -681,12 +699,11 @@ Attributes and underlying data
    Panel.ndim
    Panel.shape
 
-Conversion / Constructors
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Conversion
+~~~~~~~~~~
 .. autosummary::
    :toctree: generated/
 
-   Panel.__init__
    Panel.astype
    Panel.copy
    Panel.isnull
@@ -853,6 +870,11 @@ Index
 **Many of these methods or variants thereof are available on the objects that contain an index (Series/Dataframe)
 and those should most likely be used before calling these methods directly.**
 
+.. autosummary::
+   :toctree: generated/
+
+   Index
+
 Modifying and Computations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. autosummary::
@@ -934,6 +956,11 @@ Properties
 DatetimeIndex
 -------------
 
+.. autosummary::
+   :toctree: generated/
+
+   DatetimeIndex
+
 Time/Date Components
 ~~~~~~~~~~~~~~~~~~~~
   * **year**

doc/source/conf.py

@@ -51,7 +51,7 @@
               ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates', '_templates/autosummary']
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'

doc/sphinxext/docscrape.py

@@ -8,7 +8,7 @@
 import pydoc
 from StringIO import StringIO
 from warnings import warn
-
+import collections
 
 class Reader(object):
 
@@ -473,6 +473,8 @@ def __str__(self):
 
 class ClassDoc(NumpyDocString):
 
+    extra_public_methods = ['__call__']
+
     def __init__(self, cls, doc=None, modulename='', func_doc=FunctionDoc,
                  config={}):
         if not inspect.isclass(cls) and cls is not None:
@@ -502,12 +504,16 @@ def __init__(self, cls, doc=None, modulename='', func_doc=FunctionDoc,
     def methods(self):
         if self._cls is None:
             return []
-        return [name for name, func in inspect.getmembers(self._cls)
-                if not name.startswith('_') and callable(func)]
+        return [name for name,func in inspect.getmembers(self._cls)
+                if ((not name.startswith('_')
+                     or name in self.extra_public_methods)
+                    and isinstance(func, collections.Callable))]
 
     @property
     def properties(self):
         if self._cls is None:
             return []
-        return [name for name, func in inspect.getmembers(self._cls)
-                if not name.startswith('_') and func is None]
+        return [name for name,func in inspect.getmembers(self._cls)
+                if not name.startswith('_') and
+                (func is None or isinstance(func, property) or
+                 inspect.isgetsetdescriptor(func))]