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

Author: jschendel

ci/code_checks.sh

@@ -145,6 +145,13 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
         -k"-crosstab -pivot_table -cut"
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
+    MSG='Doctests interval classes' ; echo $MSG
+    pytest --doctest-modules -v \
+        pandas/core/indexes/interval.py \
+        pandas/core/arrays/interval.py \
+        -k"-from_arrays -from_breaks -from_intervals -from_tuples -get_loc -set_closed -to_tuples -interval_range"
+    RET=$(($RET + $?)) ; echo $MSG "DONE"
+
 fi
 
 exit $RET

pandas/core/arrays/interval.py

@@ -33,7 +33,8 @@
 )
 
 
-_interval_shared_docs['class'] = """%(summary)s
+_interval_shared_docs['class'] = """
+%(summary)s
 
 .. versionadded:: %(versionadded)s
 
@@ -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
 ----------
@@ -87,18 +90,35 @@
 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
 """
 
 
+# TODO(jschendel) use a more direct call in Examples when made public (GH22860)
 @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)])
+    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):

pandas/core/indexes/interval.py

@@ -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.
          """),
          ))
 
@@ -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`,