DOC: add references for different index types + examples for pd.Index (#17680)

Author: topper-123

doc/source/api.rst

@@ -1626,6 +1626,52 @@ Conversion
 
 .. currentmodule:: pandas
 
+PeriodIndex
+--------------
+
+.. autosummary::
+   :toctree: generated/
+   :template: autosummary/class_without_autosummary.rst
+
+   PeriodIndex
+
+Attributes
+~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+
+    PeriodIndex.day
+    PeriodIndex.dayofweek
+    PeriodIndex.dayofyear
+    PeriodIndex.days_in_month
+    PeriodIndex.daysinmonth
+    PeriodIndex.end_time
+    PeriodIndex.freq
+    PeriodIndex.freqstr
+    PeriodIndex.hour
+    PeriodIndex.is_leap_year
+    PeriodIndex.minute
+    PeriodIndex.month
+    PeriodIndex.quarter
+    PeriodIndex.qyear
+    PeriodIndex.second
+    PeriodIndex.start_time
+    PeriodIndex.week
+    PeriodIndex.weekday
+    PeriodIndex.weekofyear
+    PeriodIndex.year
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: generated/
+
+    PeriodIndex.asfreq
+    PeriodIndex.strftime
+    PeriodIndex.to_timestamp
+    PeriodIndex.tz_convert
+    PeriodIndex.tz_localize
+
 Scalars
 -------
 
@@ -1653,13 +1699,11 @@ Attributes
     Period.is_leap_year
     Period.minute
     Period.month
-    Period.now
     Period.ordinal
     Period.quarter
     Period.qyear
     Period.second
     Period.start_time
-    Period.strftime
     Period.week
     Period.weekday
     Period.weekofyear
@@ -1671,6 +1715,7 @@ Methods
     :toctree: generated/
 
     Period.asfreq
+    Period.now
     Period.strftime
     Period.to_timestamp
 

doc/sphinxext/numpydoc/numpydoc.py

@@ -45,7 +45,7 @@ def mangle_docstrings(app, what, name, obj, options, lines,
     # PANDAS HACK (to remove the list of methods/attributes for Categorical)
     no_autosummary = [".Categorical", "CategoricalIndex", "IntervalIndex",
                       "RangeIndex", "Int64Index", "UInt64Index",
-                      "Float64Index"]
+                      "Float64Index", "PeriodIndex"]
     if what == "class" and any(name.endswith(n) for n in no_autosummary):
         cfg['class_members_list'] = False
 

pandas/core/indexes/base.py

@@ -123,6 +123,23 @@ class Index(IndexOpsMixin, PandasObject):
     Notes
     -----
     An Index instance can **only** contain hashable objects
+
+    Examples
+    --------
+    >>> pd.Index([1, 2, 3])
+    Int64Index([1, 2, 3], dtype='int64')
+
+    >>> pd.Index(list('abc'))
+    Index(['a', 'b', 'c'], dtype='object')
+
+    See Also
+    ---------
+    RangeIndex : Index implementing a monotonic integer range
+    CategoricalIndex : Index of :class:`Categorical` s.
+    MultiIndex : A multi-level, or hierarchical, Index
+    IntervalIndex : an Index of :class:`Interval` s.
+    DatetimeIndex, TimedeltaIndex, PeriodIndex
+    Int64Index, UInt64Index,  Float64Index
     """
     # To hand over control to subclasses
     _join_precedence = 1

pandas/core/indexes/datetimes.py

@@ -208,9 +208,14 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin,
 
     Notes
     -----
-
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.
+
+    See Also
+    ---------
+    Index : The base pandas Index type
+    TimedeltaIndex : Index of timedelta64 data
+    PeriodIndex : Index of Period data
     """
 
     _typ = 'datetimeindex'

pandas/core/indexes/interval.py

@@ -147,7 +147,7 @@ class IntervalIndex(IntervalMixin, Index):
 
     See Also
     --------
-    Index
+    Index : The base pandas Index type
     Interval : A bounded slice-like interval
     interval_range : Function to create a fixed frequency
     IntervalIndex, IntervalIndex.from_arrays, IntervalIndex.from_breaks,

pandas/core/indexes/multi.py

@@ -95,6 +95,7 @@ class MultiIndex(Index):
     MultiIndex.from_product : Create a MultiIndex from the cartesian product
                               of iterables
     MultiIndex.from_tuples  : Convert list of tuples to a MultiIndex
+    Index : The base pandas Index type
     """
 
     # initialize to zero-length tuples to make everything work

pandas/core/indexes/numeric.py

@@ -108,19 +108,21 @@ def is_all_dates(self):
         Make a copy of input ndarray
     name : object
         Name to be stored in the index
+
     Notes
     -----
     An Index instance can **only** contain hashable objects.
+
+    See also
+    --------
+    Index : The base pandas Index type
 """
 
 _int64_descr_args = dict(
     klass='Int64Index',
     ltype='integer',
     dtype='int64',
-    extra="""This is the default index type used
-    by the DataFrame and Series ctors when no explicit
-    index is provided by the user.
-"""
+    extra=''
 )
 
 

pandas/core/indexes/period.py

@@ -164,6 +164,13 @@ class PeriodIndex(DatelikeOps, DatetimeIndexOpsMixin, Int64Index):
     >>> idx = PeriodIndex(year=year_arr, quarter=q_arr)
 
     >>> idx2 = PeriodIndex(start='2000', end='2010', freq='A')
+
+    See Also
+    ---------
+    Index : The base pandas Index type
+    Period : Represents a period of time
+    DatetimeIndex : Index with datetime64 data
+    TimedeltaIndex : Index of timedelta64 data
     """
     _box_scalars = True
     _typ = 'periodindex'

pandas/core/indexes/range.py

@@ -23,9 +23,14 @@
 class RangeIndex(Int64Index):
 
     """
-    Immutable Index implementing a monotonic range. RangeIndex is a
-    memory-saving special case of Int64Index limited to representing
-    monotonic ranges.
+    Immutable 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.
+
+    This is the default index type used
+    by DataFrame and Series when no explicit index is provided by the user.
 
     Parameters
     ----------
@@ -38,6 +43,10 @@ class RangeIndex(Int64Index):
     copy : bool, default False
         Unused, accepted for homogeneity with other index types.
 
+    See Also
+    --------
+    Index : The base pandas Index type
+    Int64Index : Index of int64 data
     """
 
     _typ = 'rangeindex'

pandas/core/indexes/timedeltas.py

@@ -114,6 +114,13 @@ class TimedeltaIndex(DatetimeIndexOpsMixin, TimelikeOps, Int64Index):
 
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.
+
+    See Also
+    ---------
+    Index : The base pandas Index type
+    Timedelta : Represents a duration between two dates or times.
+    DatetimeIndex : Index of datetime64 data
+    PeriodIndex : Index of Period data
     """
 
     _typ = 'timedeltaindex'