Bug22373: Enhance documentation for RangeIndex

pandas/core/indexes/base.py

@@ -177,7 +177,7 @@ class Index(IndexOpsMixin, PandasObject):
 
     Parameters
     ----------
-    data : array-like (1-dimensional)
+    data : array-like (1-dimensional) or python `range`
     dtype : NumPy dtype (default: object)
         If dtype is None, we find the dtype that best fits the data.
         If an actual dtype is provided, we coerce to that dtype if it's safe.
@@ -201,6 +201,9 @@ class Index(IndexOpsMixin, PandasObject):
     >>> pd.Index(list('abc'))
     Index(['a', 'b', 'c'], dtype='object')
 
+    >>> pd.Index(range(4))
+    RangeIndex(start=0, stop=4, step=1)
+
     See Also
     ---------
     RangeIndex : Index implementing a monotonic integer range

pandas/core/indexes/range.py

@@ -28,31 +28,69 @@
 class RangeIndex(Int64Index):
 
     """
-    Immutable Index implementing a monotonic integer range.
+    Immutable :class:`~pandas.Index` implementing a monotonic integer range.
 
-    RangeIndex is a memory-saving special case of Int64Index limited to
-    representing monotonic ranges. Using RangeIndex may in some instances
-    improve computing speed.
+    Most users do not need to use this class and should instead pass a python
+    `range` to :class:`~pandas.Index` to construct a `RangeIndex`.
+
+    Like a python `range`, a `RangeIndex` contains values from `start`
+    (inclusive) to `stop` (exclusive)
+    with increments of size `step`. This means that for a positive `step`,
+    the contents of a `RangeIndex` r are determined by
+    the formula ``r[i] = start + step*i where i >= 0 and r[i] < stop``.
+    Accordingly, for a negative `step`, the contents of the `RangeIndex` are
+    still determined by the formula ``r[i] = start + step*i``, but the constraints
+    are ``i >= 0 and r[i] > stop``.
+
+    `RangeIndex` is a memory-saving special case of :class:`~pandas.Int64Index`
+    limited to representing monotonic ranges. Using `RangeIndex` may in some
+    instances improve computing speed.
 
     This is the default index type used
-    by DataFrame and Series when no explicit index is provided by the user.
+    by `DataFrame` and `Series` when no explicit index is provided by the user.
 
     Parameters
     ----------
-    start : int (default: 0), or other RangeIndex instance.
-        If int and "stop" is not given, interpreted as "stop" instead.
-    stop : int (default: 0)
-    step : int (default: 1)
-    name : object, optional
-        Name to be stored in the index
+    start : int or other RangeIndex instance, default 0
+        If of type `int` and `stop` is not given, interpreted as `stop`
+        instead.
+    stop : int, default 0
+    step : int, default 1
+    dtype : numpy dtype or pandas type, default int64
+        Only the default `int64` is supported, argument accepted for
+        homogeneity with other index types.
     copy : bool, default False
         Unused, accepted for homogeneity with other index types.
+    name : object, optional
+        Name to be stored in the index
+    fastpath : bool, default False
+        Do not validate arguments. If `fastpath` is `True`, `start` has to be
+        of type `int`.
 
     See Also
     --------
     Index : The base pandas Index type
     Int64Index : Index of int64 data
 
+    Examples
+    --------
+    Most users should use :class:`~pandas.RangeIndex` to construct a
+    `RangeIndex`.
+
+    >>> pd.Index(range(4))
+    RangeIndex(start=0, stop=4, step=1)
+
+    However, `RangeIndex` can also directly be constructed.
+
+    >>> pd.RangeIndex(0, 4, 1)
+    RangeIndex(start=0, stop=4, step=1)
+
+    The step and start parameters are optional, and `RangeIndex` excludes stop:
+
+    >>> list(pd.RangeIndex(4))
+    [0, 1, 2, 3]
+
+
     Attributes
     ----------
     None
@@ -119,7 +157,20 @@ def ensure_int(value, field):
 
     @classmethod
     def from_range(cls, data, name=None, dtype=None, **kwargs):
-        """ create RangeIndex from a range (py3), or xrange (py2) object """
+        """
+        Create RangeIndex from a range (py3), or xrange (py2) object.
+
+        Parameters
+        ----------
+        data : range (py3), or xrange (py2)
+        name : object
+             Name to be stored in the index
+        dtype : numpy dtype or pandas type, default int64
+            Only the default int64 is supported, argument accepted for
+            homogeneity with other index types.
+        **kwargs
+            These parameters will be passed to :class:`~pandas.RangeIndex`.
+        """
         if not isinstance(data, range):
             raise TypeError(
                 '{0}(...) must be called with object coercible to a '