From f50a99156e05f86d88ac0e8b4a39fa5b2a3090d0 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 8 Oct 2013 22:40:29 +0200 Subject: [PATCH] DOC: add DataFrame et al class docstring to api docs + add template class.rst (copied from numpy) + adapt sphinxext numpydoc (was outdated, attributes not included) --- doc/source/_templates/autosummary/class.rst | 33 +++++++++++++++ doc/source/api.rst | 47 ++++++++++++++++----- doc/source/conf.py | 2 +- doc/sphinxext/docscrape.py | 16 ++++--- 4 files changed, 82 insertions(+), 16 deletions(-) create mode 100644 doc/source/_templates/autosummary/class.rst diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst new file mode 100644 index 0000000000000..e9af7e8df8bab --- /dev/null +++ b/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 %} diff --git a/doc/source/api.rst b/doc/source/api.rst index 2e817e9d19c3f..46d77d0dcceb7 100644 --- a/doc/source/api.rst +++ b/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** diff --git a/doc/source/conf.py b/doc/source/conf.py index 99d1703b9ca34..a500289b27ab1 100644 --- a/doc/source/conf.py +++ b/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' diff --git a/doc/sphinxext/docscrape.py b/doc/sphinxext/docscrape.py index 9a8ac59b32714..a8323c2c74361 100755 --- a/doc/sphinxext/docscrape.py +++ b/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))] \ No newline at end of file