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 a left and
+                                right array
+    IntervalIndex.from_breaks : Construct an IntervalIndex from an array of
+                                splits
+    IntervalIndex.from_intervals : Construct an IntervalIndex from a array of
+                                   Interval objects
+    IntervalIndex.from_tuples : Construct an IntervalIndex from a list/array of
+                                tuples
     """
     _typ = 'intervalindex'
     _comparables = ['name']
@@ -415,7 +448,9 @@ 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]')
         """
         left = []
         right = []
@@ -1159,6 +1194,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, '