Skip to content

DOC: document subclasses in API docs with selection of specific methods/attributes #18202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 34 commits into from
Nov 15, 2017
Merged

DOC: document subclasses in API docs with selection of specific methods/attributes #18202

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
500ab71
DOC: Remove numpydoc hack, list methods explicitly
TomAugspurger Nov 9, 2017
257fc8a
[WIP]: API doc
TomAugspurger Nov 9, 2017
d59c0b5
More explicit methods
TomAugspurger Nov 10, 2017
cb57504
More updates
TomAugspurger Nov 10, 2017
5e4cf6d
typos
TomAugspurger Nov 10, 2017
346a73b
Merge remote-tracking branch 'upstream/master' into api-doc-methods
TomAugspurger Nov 11, 2017
b5902ff
more
TomAugspurger Nov 12, 2017
af1e866
Merge remote-tracking branch 'upstream/master' into api-doc-methods
TomAugspurger Nov 12, 2017
874aefe
Add accessors to hidden
TomAugspurger Nov 12, 2017
32c2816
Remove dupe section
TomAugspurger Nov 12, 2017
38673bd
Added Categorical
TomAugspurger Nov 12, 2017
e30335e
More fixups
TomAugspurger Nov 13, 2017
38efdcb
More cleanups
TomAugspurger Nov 13, 2017
5e8bcbe
PEP8
TomAugspurger Nov 13, 2017
8695727
Hide more items
TomAugspurger Nov 13, 2017
4476a5f
Fixups
TomAugspurger Nov 13, 2017
a5005e1
Matching NaT
TomAugspurger Nov 13, 2017
aa92592
Fix typo
TomAugspurger Nov 13, 2017
8841035
Merge remote-tracking branch 'upstream/master' into api-doc-methods
TomAugspurger Nov 13, 2017
1527cdb
PEP8
TomAugspurger Nov 13, 2017
7ca3434
Fix ordering, escaping
TomAugspurger Nov 14, 2017
5a0e10e
Add notes on contributing
TomAugspurger Nov 14, 2017
c8504d1
Fix kwds again
TomAugspurger Nov 14, 2017
f7ed015
Wording
TomAugspurger Nov 14, 2017
094f6f6
Fix ref
TomAugspurger Nov 14, 2017
1c2160f
Another fixup
TomAugspurger Nov 14, 2017
6e99be2
Series of dtype category
TomAugspurger Nov 14, 2017
3bd03db
Move more methods to hidden
TomAugspurger Nov 14, 2017
ba257cc
Hide get_loc
TomAugspurger Nov 14, 2017
169e833
Merge remote-tracking branch 'upstream/master' into api-doc-methods
TomAugspurger Nov 14, 2017
f846713
Just hide attributes
TomAugspurger Nov 14, 2017
141107a
Cleanup hidden
TomAugspurger Nov 14, 2017
3a224be
remove some methods from api.rst
jorisvandenbossche Nov 15, 2017
34834fa
fix warning for float64index
jorisvandenbossche Nov 15, 2017
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 85 additions & 1 deletion doc/source/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -653,6 +653,12 @@ The dtype of a ``Categorical`` can be described by a :class:`pandas.api.types.Ca

api.types.CategoricalDtype

.. autosummary::
:toctree: generated/

api.types.CategoricalDtype.categories
api.types.CategoricalDtype.ordered

If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical
data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the
following usable methods and properties:
Expand Down Expand Up @@ -692,6 +698,10 @@ adding ordering information or special categories is need at creation time of th
.. autosummary::
:toctree: generated/

Categorical.categories
Copy link
Contributor Author

@TomAugspurger TomAugspurger Nov 9, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that this is the wrong place for this (doesn't fit w/ the text above). I'm going to make a dedicated section for Categorical.
Categorical.ordered
Categorical.codes
Categorical.dtype
Categorical.from_codes

``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts
Expand Down Expand Up @@ -792,11 +802,14 @@ Attributes and underlying data
DataFrame.get_ftype_counts
DataFrame.select_dtypes
DataFrame.values
DataFrame.get_values
DataFrame.axes
DataFrame.ndim
DataFrame.size
DataFrame.shape
DataFrame.memory_usage
DataFrame.empty
DataFrame.is_copy

Conversion
~~~~~~~~~~
Expand All @@ -809,6 +822,7 @@ Conversion
DataFrame.copy
DataFrame.isna
DataFrame.notna
DataFrame.bool

Indexing, iteration
~~~~~~~~~~~~~~~~~~~
Expand All @@ -821,14 +835,18 @@ Indexing, iteration
DataFrame.loc
DataFrame.iloc
DataFrame.insert
DataFrame.insert
DataFrame.__iter__
DataFrame.items
DataFrame.keys
DataFrame.iteritems
DataFrame.iterrows
DataFrame.itertuples
DataFrame.lookup
DataFrame.pop
DataFrame.tail
DataFrame.xs
DataFrame.get
DataFrame.isin
DataFrame.where
DataFrame.mask
Expand All @@ -845,12 +863,16 @@ Binary operator functions

DataFrame.add
DataFrame.sub
DataFrame.subtract
Copy link
Contributor Author

@TomAugspurger TomAugspurger Nov 9, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thoughts on these aliases? IMO, since there methods we should document them. But I can also put them in our "hidden" block down below.
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should document them in the sense that they have a docstring and will end up in the class docstring page of DataFrame in the full list of members, but I don't think that should mean we should include them all in this place.
DataFrame.mul
DataFrame.multiply
DataFrame.div
DataFrame.divide
DataFrame.truediv
DataFrame.floordiv
DataFrame.mod
DataFrame.pow
DataFrame.dot
DataFrame.radd
DataFrame.rsub
DataFrame.rmul
Expand All @@ -875,6 +897,8 @@ Function application, GroupBy & Window

DataFrame.apply
DataFrame.applymap
DataFrame.pipe
DataFrame.agg
DataFrame.aggregate
DataFrame.transform
DataFrame.groupby
Expand All @@ -895,6 +919,7 @@ Computations / Descriptive Stats
DataFrame.clip
DataFrame.clip_lower
DataFrame.clip_upper
DataFrame.compound
DataFrame.corr
DataFrame.corrwith
DataFrame.count
Expand All @@ -907,6 +932,7 @@ Computations / Descriptive Stats
DataFrame.diff
DataFrame.eval
DataFrame.kurt
DataFrame.kurtosis
DataFrame.mad
DataFrame.max
DataFrame.mean
Expand All @@ -915,6 +941,7 @@ Computations / Descriptive Stats
DataFrame.mode
DataFrame.pct_change
DataFrame.prod
DataFrame.product
DataFrame.quantile
DataFrame.rank
DataFrame.round
Expand All @@ -923,6 +950,7 @@ Computations / Descriptive Stats
DataFrame.sum
DataFrame.std
DataFrame.var
DataFrame.nunique

Reindexing / Selection / Label manipulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -932,6 +960,8 @@ Reindexing / Selection / Label manipulation
DataFrame.add_prefix
DataFrame.add_suffix
DataFrame.align
DataFrame.at_time
DataFrame.between_time
DataFrame.drop
DataFrame.drop_duplicates
DataFrame.duplicated
Expand All @@ -950,6 +980,7 @@ Reindexing / Selection / Label manipulation
DataFrame.reset_index
DataFrame.sample
DataFrame.select
DataFrame.set_axis
DataFrame.set_index
DataFrame.tail
DataFrame.take
Expand All @@ -965,13 +996,17 @@ Missing data handling
DataFrame.dropna
DataFrame.fillna
DataFrame.replace
DataFrame.interpolate
DataFrame.isnull
DataFrame.notnull
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be isna and notna ?
Copy link
Contributor Author

@TomAugspurger TomAugspurger Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are under "Conversion" (though I think Missing data handling is a better seciton?). I've moved isnull and notnull to hidden

Reshaping, sorting, transposing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. autosummary::
:toctree: generated/

DataFrame.pivot
DataFrame.pivot_table
DataFrame.reorder_levels
DataFrame.sort_values
DataFrame.sort_index
Expand All @@ -980,10 +1015,12 @@ Reshaping, sorting, transposing
DataFrame.swaplevel
DataFrame.stack
DataFrame.unstack
DataFrame.swapaxes
DataFrame.melt
DataFrame.T
DataFrame.squeeze
DataFrame.to_panel
DataFrame.to_xarray
DataFrame.T
DataFrame.transpose

Combining / joining / merging
Expand All @@ -1005,6 +1042,8 @@ Time series-related
DataFrame.asfreq
DataFrame.asof
DataFrame.shift
DataFrame.slice_shift
DataFrame.tshift
DataFrame.first_valid_index
DataFrame.last_valid_index
DataFrame.resample
Expand Down Expand Up @@ -1059,6 +1098,7 @@ Serialization / IO / Conversion
DataFrame.from_items
DataFrame.from_records
DataFrame.info
DataFrame.to_parquet
DataFrame.to_pickle
DataFrame.to_csv
DataFrame.to_hdf
Expand All @@ -1077,6 +1117,7 @@ Serialization / IO / Conversion
DataFrame.to_dense
DataFrame.to_string
DataFrame.to_clipboard
DataFrame.style

Sparse
~~~~~~
Expand Down Expand Up @@ -1438,6 +1479,15 @@ Numeric Index
UInt64Index
Float64Index

.. We need this autosummary so that the methods are generated.
.. Separate block, since they aren't classes.

.. autosummary::
:toctree: generated/

RangeIndex.from_range


.. _api.categoricalindex:

CategoricalIndex
Expand Down Expand Up @@ -1466,6 +1516,8 @@ Categorical Components
CategoricalIndex.set_categories
CategoricalIndex.as_ordered
CategoricalIndex.as_unordered
CategoricalIndex.get_loc
CategoricalIndex.map
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are those needed to include ? (I mean, do they have something categorical specific ?)

.. _api.intervalindex:

Expand All @@ -1488,6 +1540,15 @@ IntervalIndex Components
IntervalIndex.from_tuples
IntervalIndex.from_breaks
IntervalIndex.from_intervals
IntervalIndex.contains
IntervalIndex.get_loc
IntervalIndex.left
IntervalIndex.right
IntervalIndex.mid
IntervalIndex.closed
IntervalIndex.values
IntervalIndex.is_non_overlapping_monotonic


.. _api.multiindex:

Expand Down Expand Up @@ -2284,3 +2345,26 @@ Scalar introspection
api.types.is_re
api.types.is_re_compilable
api.types.is_scalar


.. This is to prevent warnings in the doc build. We don't want to encourage
.. these methods.

.. toctree::
:hidden:

generated/pandas.DataFrame.as_blocks
generated/pandas.DataFrame.ffill
generated/pandas.DataFrame.bfill
generated/pandas.DataFrame.blocks
generated/pandas.DataFrame.sortlevel
generated/pandas.DataFrame.consolidate
generated/pandas.DataFrame.set_value
generated/pandas.DataFrame.get_value

generated/pandas.Series.as_blocks
generated/pandas.Series.ffill
generated/pandas.Series.bfill
generated/pandas.Series.set_value
generated/pandas.Series.get_value
generated/pandas.Series.blocks
1 change: 1 addition & 0 deletions doc/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@
]

exclude_patterns = ['**.ipynb_checkpoints']
numpydoc_show_class_members = False
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know why this is needed?

with open("index.rst") as f:
index_rst_lines = f.readlines()
Expand Down
7 changes: 0 additions & 7 deletions doc/sphinxext/numpydoc/numpydoc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,13 +42,6 @@ def mangle_docstrings(app, what, name, obj, options, lines,
class_members_toctree=app.config.numpydoc_class_members_toctree,
)

# PANDAS HACK (to remove the list of methods/attributes for Categorical)
no_autosummary = [".Categorical", "CategoricalIndex", "IntervalIndex",
"RangeIndex", "Int64Index", "UInt64Index",
"Float64Index", "PeriodIndex", "CategoricalDtype"]
if what == "class" and any(name.endswith(n) for n in no_autosummary):
cfg['class_members_list'] = False

Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there is also some other code related to this hack that then could be removed (eg the place where I define the 'class_members_list' config). See cf40991 that added it
if what == 'module':
# Strip top title
title_re = re.compile(sixu('^\\s*[#*=]{4,}\\n[a-z0-9 -]+\\n[#*=]{4,}\\s*'),
Expand Down
5 changes: 5 additions & 0 deletions pandas/core/dtypes/dtypes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,11 @@ class CategoricalDtype(ExtensionDtype):
Must be unique, and must not contain any nulls.
ordered : bool, default False

Attributes
----------
categories
ordered

Notes
-----
This class is useful for specifying the type of a ``Categorical``
Expand Down
19 changes: 19 additions & 0 deletions pandas/core/indexes/category.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,25 @@ class CategoricalIndex(Index, accessor.PandasDelegate):
See Also
--------
Categorical, Index

Methods
-------
rename_categories
reorder_categories
add_categories
remove_categories
remove_unused_categories
set_categories
as_ordered
as_unordered
get_loc
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mentioned above as well: is there something categorical-specific about get_loc ?

(the map is fine, that has indeed some specifics that are useful)
Copy link
Contributor Author

@TomAugspurger TomAugspurger Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just saw that the example mentioned CategoricalIndex specifically. Looks pretty similar though, so I'll remove it.
map

Attributes
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Attributes before Methods?
Copy link
Contributor Author

@TomAugspurger TomAugspurger Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed all these
----------
codes
categories
ordered
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 9, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally we would add here a sentence with something like "For all other methods, see Index", but I am not sure that is allowed in Attributes / Methods sections?
Copy link
Contributor Author

@TomAugspurger TomAugspurger Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suspect not. I've been thinking of ways to handle this.

I'm not worried about people reading the source / in IPython. They already have the code or object.

I think in the Notes section we can say "See :class:Index for additional methods." or something like that.
"""

_typ = 'categoricalindex'
Expand Down
18 changes: 18 additions & 0 deletions pandas/core/indexes/interval.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,24 @@ class IntervalIndex(IntervalMixin, Index):
IntervalIndex.from_intervals, IntervalIndex.from_tuples
cut, qcut : convert arrays of continuous data into categoricals/series of
``Interval``.

Methods
-------
from_arrays
from_tuples
from_breaks
from_intervals
contains
get_loc

Attributes
----------
left
right
mid
closed
values
is_non_overlapping_monotonic
"""
_typ = 'intervalindex'
_comparables = ['name']
Expand Down
31 changes: 31 additions & 0 deletions pandas/core/indexes/period.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,37 @@ class PeriodIndex(DatelikeOps, DatetimeIndexOpsMixin, Int64Index):
Timezone for converting datetime64 data to Periods
dtype : str or PeriodDtype, default None

Attributes
----------
Copy link
Contributor

@jreback jreback Nov 13, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm maybe we can auto gen these?
day
dayofweek
dayofyear
days_in_month
daysinmonth
end_time
freq
freqstr
hour
is_leap_year
minute
month
quarter
qyear
second
start_time
week
weekday
weekofyear
year

Methods
-------
asfreq
strftime
to_timestamp
tz_convert
tz_localize

Examples
--------
>>> idx = PeriodIndex(year=year_arr, quarter=q_arr)
Expand Down
4 changes: 4 additions & 0 deletions pandas/core/indexes/range.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,10 @@ class RangeIndex(Int64Index):
--------
Index : The base pandas Index type
Int64Index : Index of int64 data

Methods
-------
from_range
Copy link
Member

@jorisvandenbossche jorisvandenbossche Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it because there is no Attributes section that you get those warnings?
(but you said they were fixed with numpydoc master? Then the other places that do an empty section with None are also not needed?)
"""

_typ = 'rangeindex'
Expand Down