Skip to content

DOC: Modify IntervalArray/IntervalIndex docstrings to pass validate_docstrings.py #23157

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 2 commits into from
Oct 24, 2018
Merged

DOC: Modify IntervalArray/IntervalIndex docstrings to pass validate_docstrings.py #23157

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fe5a3ef
DOC: Modify IntervalArray/IntervalIndex docstrings to pass validate_d…
jschendel Oct 14, 2018
af757a0
update ci/code_checks.sh and add todo
jschendel Oct 16, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 29 additions & 10 deletions pandas/core/arrays/interval.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@
)


_interval_shared_docs['class'] = """%(summary)s
_interval_shared_docs['class'] = """
%(summary)s

.. versionadded:: %(versionadded)s

Expand All @@ -50,13 +51,15 @@
closed : {'left', 'right', 'both', 'neither'}, default 'right'
Whether the intervals are closed on the left-side, right-side, both or
neither.
%(name)s\
copy : boolean, default False
Copy the meta-data.
dtype : dtype or None, default None
If None, dtype will be inferred
If None, dtype will be inferred.

.. versionadded:: 0.23.0
copy : bool, default False
Copy the input data.
%(name)s\
verify_integrity : bool, default True
Verify that the %(klass)s is valid.

Attributes
----------
Expand Down Expand Up @@ -87,18 +90,34 @@
See Also
--------
Index : The base pandas Index type
Interval : A bounded slice-like interval; the elements of an IntervalIndex
Interval : A bounded slice-like interval; the elements of an %(klass)s
interval_range : Function to create a fixed frequency IntervalIndex
cut, qcut : Convert arrays of continuous data into Categoricals/Series of
Intervals
cut : Bin values into discrete Intervals
qcut : Bin values into equal-sized Intervals based on rank or sample quantiles
"""


@Appender(_interval_shared_docs['class'] % dict(
klass="IntervalArray",
summary="Pandas array for interval data that are closed on the same side",
summary="Pandas array for interval data that are closed on the same side.",
versionadded="0.24.0",
name='', extra_methods='', examples='',
name='',
extra_methods='',
examples=textwrap.dedent("""\
Examples
--------
A new ``IntervalArray`` can be constructed directly from an array-like of
``Interval`` objects:

>>> pd.core.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)])
Copy link
Member

Choose a reason for hiding this comment

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

I think we should keep this out of the docs until we know if or how to expose this publicly (which will in any case not be pd.core.arrays.IntervalArray)

Copy link
Member Author

Choose a reason for hiding this comment

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

ci/code_checks.sh won't check the IntervalArray docstring if the Examples section is missing. I've added a TODO note to myself to modify the example once IntervalArray has been made public; can open an issue for it as well if need be.

The issue for making extension arrays public has a milestone of 0.24.0, so I should be able to address this prior to release, and it should just be a matter of pasting the updated call. Can remove the example though, if you'd still prefer that approach.

Copy link
Member Author

Choose a reason for hiding this comment

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

ping @jorisvandenbossche : thoughts on the above?

Copy link
Member

Choose a reason for hiding this comment

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

OK, let's decide about it / clean-up later

IntervalArray([(0, 1], (1, 5]],
closed='right',
dtype='interval[int64]')

It may also be constructed using one of the constructor
methods: :meth:`IntervalArray.from_arrays`,
:meth:`IntervalArray.from_breaks`, and :meth:`IntervalArray.from_tuples`.
"""),
))
@add_metaclass(_WritableDoc)
class IntervalArray(IntervalMixin, ExtensionArray):
Expand Down
8 changes: 4 additions & 4 deletions pandas/core/indexes/interval.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@
target_klass='IntervalIndex or list of Intervals',
name=textwrap.dedent("""\
name : object, optional
to be stored in the index.
Name to be stored in the index.
"""),
))

Expand Down Expand Up @@ -116,15 +116,15 @@ def _new_IntervalIndex(cls, d):
versionadded="0.20.0",
extra_methods="contains\n",
examples=textwrap.dedent("""\

Examples
--------
A new ``IntervalIndex`` is typically constructed using
:func:`interval_range`:

>>> pd.interval_range(start=0, end=5)
IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]]
closed='right', dtype='interval[int64]')
IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]],
closed='right',
dtype='interval[int64]')

It may also be constructed using one of the constructor
methods: :meth:`IntervalIndex.from_arrays`,
Expand Down