Doc improvements for IntervalIndex and Interval (pandas-dev#17714)

doc/source/advanced.rst

@@ -833,12 +833,21 @@ Of course if you need integer based selection, then use ``iloc``
 IntervalIndex
 ~~~~~~~~~~~~~
 
+:class:`IntervalIndex` together with its own dtype, ``interval`` as well as the
+:class:`Interval` scalar type,  allow first-class support in pandas for interval
+notation.
+
+The ``IntervalIndex`` allows some unique indexing and is also used as a
+return type for the categories in :func:`cut` and :func:`qcut`.
+
 .. versionadded:: 0.20.0
 
 .. warning::
 
    These indexing behaviors are provisional and may change in a future version of pandas.
 
+An ``IntervalIndex`` can be used in ``Series`` and in ``DataFrame`` as the index.
+
 .. ipython:: python
 
    df = pd.DataFrame({'A': [1, 2, 3, 4]},
@@ -860,6 +869,20 @@ If you select a lable *contained* within an interval, this will also select the
    df.loc[2.5]
    df.loc[[2.5, 3.5]]
 
+``Interval`` and ``IntervalIndex`` are used by ``cut`` and ``qcut``:
+
+.. ipython:: python
+
+   c = pd.cut(range(4), bins=2)
+   c
+   c.categories
+
+Furthermore, ``IntervalIndex`` allows one to bin *other* data with these same
+bins, with ``NaN`` representing a missing value similar to other dtypes.
+
+.. ipython:: python
+
+   pd.cut([0, 3, 5, 1], bins=c.categories)
 
 Miscellaneous indexing FAQ
 --------------------------

pandas/_libs/interval.pyx

@@ -51,17 +51,35 @@ cdef class Interval(IntervalMixin):
 
     .. versionadded:: 0.20.0
 
-    Attributes
+    Parameters
     ----------
-    left, right : values
-        Left and right bounds for each interval.
+    left : value
+        Left bound for interval.
+    right : value
+        Right bound for interval.
     closed : {'left', 'right', 'both', 'neither'}
         Whether the interval is closed on the left-side, right-side, both or
         neither. Defaults to 'right'.
 
+    Examples
+    --------
+    >>> iv = pd.Interval(left=0, right=5)
+    >>> iv
+    Interval(0, 5, closed='right')
+    >>> 2.5 in iv
+    True
+
+    >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'),
+    ...                         pd.Timestamp('2017-12-31'), closed='both')
+    >>> pd.Timestamp('2017-01-01 00:00') in year_2017
+    True
+
     See Also
     --------
-    IntervalIndex : an Index of intervals that are all closed on the same side.
+    IntervalIndex : an Index of ``interval`` s that are all closed on the same
+                    side.
+    cut, qcut : convert arrays of continuous data into categoricals/series of
+                ``Interval``.
     """
 
     cdef readonly object left, right

pandas/core/indexes/interval.py

@@ -105,8 +105,10 @@ class IntervalIndex(IntervalMixin, Index):
 
     .. versionadded:: 0.20.0
 
-    Warning: the indexing behaviors are provisional and may change in
-    a future version of pandas.
+    .. warning::
+
+       The indexing behaviors are provisional and may change in
+       a future version of pandas.
 
     Attributes
     ----------
@@ -147,15 +149,11 @@ class IntervalIndex(IntervalMixin, Index):
     --------
     Index
     Interval : A bounded slice-like interval
-    interval_range : Function to create a fixed frequency IntervalIndex
-    IntervalIndex.from_arrays : Construct an IntervalIndex from a left and
-                                right array
-    IntervalIndex.from_breaks : Construct an IntervalIndex from an array of
-                                splits
-    IntervalIndex.from_intervals : Construct an IntervalIndex from an array of
-                                   Interval objects
-    IntervalIndex.from_tuples : Construct an IntervalIndex from a list/array of
-                                tuples
+    interval_range : Function to create a fixed frequency
+    IntervalIndex, IntervalIndex.from_arrays, IntervalIndex.from_breaks,
+    IntervalIndex.from_intervals, IntervalIndex.from_tuples
+    cut, qcut : convert arrays of continuous data into categoricals/series of
+                ``Interval``.
     """
     _typ = 'intervalindex'
     _comparables = ['name']