Improved doc string for IntervalIndex + related changes

Author: tp

pandas/_libs/interval.pyx

@@ -58,6 +58,10 @@ cdef class Interval(IntervalMixin):
     closed : {'left', 'right', 'both', 'neither'}
         Whether the interval is closed on the left-side, right-side, both or
         neither. Defaults to 'right'.
+
+    See Also
+    --------
+    IntervalIndex : an Index of intervals that are all closed on the same side.
     """
 
     cdef readonly object left, right

pandas/core/indexes/interval.py

@@ -120,9 +120,42 @@ class IntervalIndex(IntervalMixin, Index):
     copy : boolean, default False
         Copy the meta-data
 
+    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]')
+
+    It may also be constructed using one of the constructor
+    methods :meth:`IntervalIndex.from_arrays`,
+    :meth:`IntervalIndex.from_breaks`, :meth:`IntervalIndex.from_intervals`
+    and :meth:`IntervalIndex.from_tuples`.
+
+    See further examples in the doc strings of ``interval_range`` and the
+    mentioned constructor methods.
+
+    Notes
+    ------
+    See the `user guide
+    <http://pandas.pydata.org/pandas-docs/stable/advanced.html#intervalindex>`_
+    for more.
+
     See Also
     --------
     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
     """
     _typ = 'intervalindex'
     _comparables = ['name']
@@ -324,6 +357,16 @@ def from_breaks(cls, breaks, closed='right', name=None, copy=False):
         IntervalIndex(left=[0, 1, 2],
                       right=[1, 2, 3],
                       closed='right')
+
+        See Also
+        --------
+        interval_range : Function to create a fixed frequency IntervalIndex
+        IntervalIndex.from_arrays : Construct an IntervalIndex from a left and
+                                    right array
+        IntervalIndex.from_intervals : Construct an IntervalIndex from an array of
+                                       Interval objects
+        IntervalIndex.from_tuples : Construct an IntervalIndex from a list/array of
+                                    tuples
         """
         breaks = np.asarray(breaks)
         return cls.from_arrays(breaks[:-1], breaks[1:], closed,
@@ -355,6 +398,16 @@ def from_arrays(cls, left, right, closed='right', name=None, copy=False):
         IntervalIndex(left=[0, 1, 2],
                       right=[1, 2, 3],
                       closed='right')
+
+        See Also
+        --------
+        interval_range : Function to create a fixed frequency IntervalIndex
+        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
         """
         left = np.asarray(left)
         right = np.asarray(right)
@@ -391,6 +444,16 @@ def from_intervals(cls, data, name=None, copy=False):
         IntervalIndex(left=[0, 1],
                       right=[1, 2],
                       closed='right')
+
+        See Also
+        --------
+        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_tuples : Construct an IntervalIndex from a list/array of
+                                    tuples
         """
         data = np.asarray(data)
         left, right, closed = intervals_to_interval_bounds(data)
@@ -415,7 +478,19 @@ def from_tuples(cls, data, closed='right', name=None, copy=False):
 
         Examples
         --------
+        >>>  pd.IntervalIndex.from_tuples([(0, 1), (1,2)])
+        IntervalIndex([(0, 1], (1, 2]],
+                      closed='right', dtype='interval[int64]')
 
+        See Also
+        --------
+        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
         """
         left = []
         right = []
@@ -1159,6 +1234,10 @@ def interval_range(start=None, end=None, periods=None, freq=None,
     >>> pd.interval_range(end=5, periods=4, closed='both')
     IntervalIndex([[1, 2], [2, 3], [3, 4], [4, 5]]
                   closed='both', dtype='interval[int64]')
+
+    See Also
+    --------
+    IntervalIndex : an Index of intervals that are all closed on the same side.
     """
     if com._count_not_none(start, end, periods) != 2:
         raise ValueError('Of the three parameters: start, end, and periods, '