Skip to content

Commit d686154

Browse files
committed
Merge pull request #5160 from jorisvandenbossche/api-docs-template
DOC: add DataFrame et al class docstring to api docs
2 parents de63e00 + f50a991 commit d686154

File tree

4 files changed

+82
-16
lines changed

4 files changed

+82
-16
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{% extends "!autosummary/class.rst" %}
2+
3+
{% block methods %}
4+
{% if methods %}
5+
6+
..
7+
HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
8+
.. autosummary::
9+
:toctree:
10+
{% for item in all_methods %}
11+
{%- if not item.startswith('_') or item in ['__call__'] %}
12+
{{ name }}.{{ item }}
13+
{%- endif -%}
14+
{%- endfor %}
15+
16+
{% endif %}
17+
{% endblock %}
18+
19+
{% block attributes %}
20+
{% if attributes %}
21+
22+
..
23+
HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
24+
.. autosummary::
25+
:toctree:
26+
{% for item in all_attributes %}
27+
{%- if not item.startswith('_') %}
28+
{{ name }}.{{ item }}
29+
{%- endif -%}
30+
{%- endfor %}
31+
32+
{% endif %}
33+
{% endblock %}

doc/source/api.rst

+37-10
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,13 @@ Exponentially-weighted moving window functions
206206
Series
207207
------
208208

209+
Constructor
210+
~~~~~~~~~~~
211+
.. autosummary::
212+
:toctree: generated/
213+
214+
Series
215+
209216
Attributes and underlying data
210217
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211218
**Axes**
@@ -219,13 +226,11 @@ Attributes and underlying data
219226
Series.isnull
220227
Series.notnull
221228

222-
Conversion / Constructors
223-
~~~~~~~~~~~~~~~~~~~~~~~~~
224-
229+
Conversion
230+
~~~~~~~~~~
225231
.. autosummary::
226232
:toctree: generated/
227233

228-
Series.__init__
229234
Series.astype
230235
Series.copy
231236
Series.isnull
@@ -418,6 +423,13 @@ Serialization / IO / Conversion
418423
DataFrame
419424
---------
420425

426+
Constructor
427+
~~~~~~~~~~~
428+
.. autosummary::
429+
:toctree: generated/
430+
431+
DataFrame
432+
421433
Attributes and underlying data
422434
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
423435
**Axes**
@@ -436,12 +448,11 @@ Attributes and underlying data
436448
DataFrame.ndim
437449
DataFrame.shape
438450

439-
Conversion / Constructors
440-
~~~~~~~~~~~~~~~~~~~~~~~~~
451+
Conversion
452+
~~~~~~~~~~
441453
.. autosummary::
442454
:toctree: generated/
443455

444-
DataFrame.__init__
445456
DataFrame.astype
446457
DataFrame.convert_objects
447458
DataFrame.copy
@@ -665,6 +676,13 @@ Serialization / IO / Conversion
665676
Panel
666677
------
667678

679+
Constructor
680+
~~~~~~~~~~~
681+
.. autosummary::
682+
:toctree: generated/
683+
684+
Panel
685+
668686
Attributes and underlying data
669687
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
670688
**Axes**
@@ -681,12 +699,11 @@ Attributes and underlying data
681699
Panel.ndim
682700
Panel.shape
683701

684-
Conversion / Constructors
685-
~~~~~~~~~~~~~~~~~~~~~~~~~
702+
Conversion
703+
~~~~~~~~~~
686704
.. autosummary::
687705
:toctree: generated/
688706

689-
Panel.__init__
690707
Panel.astype
691708
Panel.copy
692709
Panel.isnull
@@ -853,6 +870,11 @@ Index
853870
**Many of these methods or variants thereof are available on the objects that contain an index (Series/Dataframe)
854871
and those should most likely be used before calling these methods directly.**
855872

873+
.. autosummary::
874+
:toctree: generated/
875+
876+
Index
877+
856878
Modifying and Computations
857879
~~~~~~~~~~~~~~~~~~~~~~~~~~
858880
.. autosummary::
@@ -934,6 +956,11 @@ Properties
934956
DatetimeIndex
935957
-------------
936958

959+
.. autosummary::
960+
:toctree: generated/
961+
962+
DatetimeIndex
963+
937964
Time/Date Components
938965
~~~~~~~~~~~~~~~~~~~~
939966
* **year**

doc/source/conf.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
]
5252

5353
# Add any paths that contain templates here, relative to this directory.
54-
templates_path = ['_templates', '_templates/autosummary']
54+
templates_path = ['_templates']
5555

5656
# The suffix of source filenames.
5757
source_suffix = '.rst'

doc/sphinxext/docscrape.py

+11-5
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
import pydoc
99
from StringIO import StringIO
1010
from warnings import warn
11-
11+
import collections
1212

1313
class Reader(object):
1414

@@ -473,6 +473,8 @@ def __str__(self):
473473

474474
class ClassDoc(NumpyDocString):
475475

476+
extra_public_methods = ['__call__']
477+
476478
def __init__(self, cls, doc=None, modulename='', func_doc=FunctionDoc,
477479
config={}):
478480
if not inspect.isclass(cls) and cls is not None:
@@ -502,12 +504,16 @@ def __init__(self, cls, doc=None, modulename='', func_doc=FunctionDoc,
502504
def methods(self):
503505
if self._cls is None:
504506
return []
505-
return [name for name, func in inspect.getmembers(self._cls)
506-
if not name.startswith('_') and callable(func)]
507+
return [name for name,func in inspect.getmembers(self._cls)
508+
if ((not name.startswith('_')
509+
or name in self.extra_public_methods)
510+
and isinstance(func, collections.Callable))]
507511

508512
@property
509513
def properties(self):
510514
if self._cls is None:
511515
return []
512-
return [name for name, func in inspect.getmembers(self._cls)
513-
if not name.startswith('_') and func is None]
516+
return [name for name,func in inspect.getmembers(self._cls)
517+
if not name.startswith('_') and
518+
(func is None or isinstance(func, property) or
519+
inspect.isgetsetdescriptor(func))]

0 commit comments

Comments
 (0)