DOC: Fix section headers in docstrings (#26301)

pandas/core/arrays/base.py

@@ -1059,8 +1059,8 @@ def _create_method(cls, op, coerce_to_dtype=True):
             `op` cannot be stored in the ExtensionArray. The dtype of the
             ndarray uses NumPy's normal inference rules.
 
-        Example
-        -------
+        Examples
+        --------
         Given an ExtensionArray subclass called MyExtensionArray, use
 
         >>> __add__ = cls._create_method(operator.add)

pandas/core/arrays/categorical.py

@@ -2140,23 +2140,18 @@ def _reverse_indexer(self):
         -------
         dict of categories -> indexers
 
-        Example
-        -------
-        In [1]: c = pd.Categorical(list('aabca'))
-
-        In [2]: c
-        Out[2]:
+        Examples
+        --------
+        >>> c = pd.Categorical(list('aabca'))
+        >>> c
         [a, a, b, c, a]
         Categories (3, object): [a, b, c]
-
-        In [3]: c.categories
-        Out[3]: Index(['a', 'b', 'c'], dtype='object')
-
-        In [4]: c.codes
-        Out[4]: array([0, 0, 1, 2, 0], dtype=int8)
-
-        In [5]: c._reverse_indexer()
-        Out[5]: {'a': array([0, 1, 4]), 'b': array([2]), 'c': array([3])}
+        >>> c.categories
+        Index(['a', 'b', 'c'], dtype='object')
+        >>> c.codes
+        array([0, 0, 1, 2, 0], dtype=int8)
+        >>> c._reverse_indexer()
+        {'a': array([0, 1, 4]), 'b': array([2]), 'c': array([3])}
 
         """
         categories = self.categories

pandas/core/arrays/datetimes.py

@@ -586,7 +586,7 @@ def __iter__(self):
         Return an iterator over the boxed values
 
         Yields
-        -------
+        ------
         tstamp : Timestamp
         """
 

pandas/core/arrays/interval.py

@@ -93,7 +93,7 @@
 qcut : Bin values into equal-sized Intervals based on rank or sample quantiles.
 
 Notes
-------
+-----
 See the `user guide
 <http://pandas.pydata.org/pandas-docs/stable/advanced.html#intervalindex>`_
 for more.

pandas/core/arrays/sparse.py

@@ -1955,7 +1955,7 @@ def from_coo(cls, A, dense_index=False):
         s : SparseSeries
 
         Examples
-        ---------
+        --------
         >>> from scipy import sparse
         >>> A = sparse.coo_matrix(([3.0, 1.0, 2.0], ([1, 0, 0], [0, 2, 3])),
                                shape=(3, 4))

pandas/core/dtypes/common.py

@@ -763,7 +763,7 @@ def is_dtype_equal(source, target):
     target : The second dtype to compare
 
     Returns
-    ----------
+    -------
     boolean
         Whether or not the two dtypes are equal.
 
@@ -804,7 +804,7 @@ def is_dtype_union_equal(source, target):
     target : The second dtype to compare
 
     Returns
-    ----------
+    -------
     boolean
         Whether or not the two dtypes are equal.
 

pandas/core/frame.py

@@ -7250,7 +7250,7 @@ def corrwith(self, other, axis=0, drop=False, method='pearson'):
             Pairwise correlations.
 
         See Also
-        -------
+        --------
         DataFrame.corr
         """
         axis = self._get_axis_number(axis)

pandas/core/generic.py

@@ -10327,11 +10327,11 @@ def transform(self, func, *args, **kwargs):
         Return index for %(position)s non-NA/null value.
 
         Returns
-        --------
+        -------
         scalar : type of index
 
         Notes
-        --------
+        -----
         If all elements are non-NA/null, returns None.
         Also returns None for empty %(klass)s.
         """

pandas/core/groupby/groupby.py

@@ -799,13 +799,13 @@ def _try_cast(self, result, obj, numeric_only=False):
 
     def _transform_should_cast(self, func_nm):
         """
-        Parameters:
-        -----------
+        Parameters
+        ----------
         func_nm: str
             The name of the aggregation function being performed
 
-        Returns:
-        --------
+        Returns
+        -------
         bool
             Whether transform should attempt to cast the result of aggregation
         """

pandas/core/indexes/base.py

@@ -183,7 +183,7 @@ class Index(IndexOpsMixin, PandasObject):
         When True, attempt to create a MultiIndex if possible
 
     See Also
-    ---------
+    --------
     RangeIndex : Index implementing a monotonic integer range.
     CategoricalIndex : Index of :class:`Categorical` s.
     MultiIndex : A multi-level, or hierarchical, Index.
@@ -2649,7 +2649,7 @@ def _convert_can_do_setop(self, other):
         loc : int if unique index, slice if monotonic index, else mask
 
         Examples
-        ---------
+        --------
         >>> unique_index = pd.Index(list('abc'))
         >>> unique_index.get_loc('b')
         1
@@ -4699,7 +4699,7 @@ def slice_indexer(self, start=None, end=None, step=None, kind=None):
         This function assumes that the data is sorted, so use at your own peril
 
         Examples
-        ---------
+        --------
         This is a method on all index types. For example you can do:
 
         >>> idx = pd.Index(list('abcd'))
@@ -4902,7 +4902,7 @@ def slice_locs(self, start=None, end=None, step=None, kind=None):
         This method only works if the index is monotonic or unique.
 
         Examples
-        ---------
+        --------
         >>> idx = pd.Index(list('abcd'))
         >>> idx.slice_locs(start='b', end='c')
         (1, 3)

pandas/core/indexes/category.py

@@ -474,7 +474,7 @@ def get_loc(self, key, method=None):
         KeyError : if the key is not in the index
 
         Examples
-        ---------
+        --------
         >>> unique_index = pd.CategoricalIndex(list('abc'))
         >>> unique_index.get_loc('b')
         1

pandas/core/indexes/datetimes.py

@@ -204,21 +204,21 @@ class DatetimeIndex(DatetimeIndexOpsMixin, Int64Index, DatetimeDelegateMixin):
     month_name
     day_name
 
+    See Also
+    --------
+    Index : The base pandas Index type.
+    TimedeltaIndex : Index of timedelta64 data.
+    PeriodIndex : Index of Period data.
+    to_datetime : Convert argument to datetime.
+    date_range : Create a fixed-frequency DatetimeIndex.
+
     Notes
     -----
     To learn more about the frequency strings, please see `this link
     <http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.
 
     Creating a DatetimeIndex based on `start`, `periods`, and `end` has
     been deprecated in favor of :func:`date_range`.
-
-    See Also
-    ---------
-    Index : The base pandas Index type.
-    TimedeltaIndex : Index of timedelta64 data.
-    PeriodIndex : Index of Period data.
-    to_datetime : Convert argument to datetime.
-    date_range : Create a fixed-frequency DatetimeIndex.
     """
     _typ = 'datetimeindex'
     _join_precedence = 10

pandas/core/indexes/interval.py

@@ -729,7 +729,7 @@ def get_loc(self, key, method=None):
         loc : int if unique index, slice if monotonic index, else mask
 
         Examples
-        ---------
+        --------
         >>> i1, i2 = pd.Interval(0, 1), pd.Interval(1, 2)
         >>> index = pd.IntervalIndex([i1, i2])
         >>> index.get_loc(1)

pandas/core/indexes/multi.py

@@ -57,7 +57,7 @@ def _codes_to_ints(self, codes):
             Combinations of integers (one per row)
 
         Returns
-        ------
+        -------
         int_keys : scalar or 1-dimensional array, of dtype uint64
             Integer(s) representing one combination (each).
         """
@@ -97,7 +97,7 @@ def _codes_to_ints(self, codes):
             Combinations of integers (one per row)
 
         Returns
-        ------
+        -------
         int_keys : int, or 1-dimensional array of dtype object
             Integer(s) representing one combination (each).
         """
@@ -179,8 +179,13 @@ class MultiIndex(Index):
     MultiIndex.from_frame   : Make a MultiIndex from a DataFrame.
     Index : The base pandas Index type.
 
+    Notes
+    -----
+    See the `user guide
+    <http://pandas.pydata.org/pandas-docs/stable/advanced.html>`_ for more.
+
     Examples
-    ---------
+    --------
     A new ``MultiIndex`` is typically constructed using one of the helper
     methods :meth:`MultiIndex.from_arrays`, :meth:`MultiIndex.from_product`
     and :meth:`MultiIndex.from_tuples`. For example (using ``.from_arrays``):
@@ -193,11 +198,6 @@ class MultiIndex(Index):
 
     See further examples for how to construct a MultiIndex in the doc strings
     of the mentioned helper methods.
-
-    Notes
-    -----
-    See the `user guide
-    <http://pandas.pydata.org/pandas-docs/stable/advanced.html>`_ for more.
     """
 
     # initialize to zero-length tuples to make everything work
@@ -1398,7 +1398,7 @@ def get_level_values(self, level):
             a single :class:`Index` (or subclass thereof).
 
         Examples
-        ---------
+        --------
 
         Create a MultiIndex:
 
@@ -2367,29 +2367,29 @@ def get_loc(self, key, method=None):
             If the key is past the lexsort depth, the return may be a
             boolean mask array, otherwise it is always a slice or int.
 
+        See Also
+        --------
+        Index.get_loc : The get_loc method for (single-level) index.
+        MultiIndex.slice_locs : Get slice location given start label(s) and
+                                end label(s).
+        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
+                              sequence of such.
+
+        Notes
+        -----
+        The key cannot be a slice, list of same-level labels, a boolean mask,
+        or a sequence of such. If you want to use those, use
+        :meth:`MultiIndex.get_locs` instead.
+
         Examples
-        ---------
+        --------
         >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')])
 
         >>> mi.get_loc('b')
         slice(1, 3, None)
 
         >>> mi.get_loc(('b', 'e'))
         1
-
-        Notes
-        ------
-        The key cannot be a slice, list of same-level labels, a boolean mask,
-        or a sequence of such. If you want to use those, use
-        :meth:`MultiIndex.get_locs` instead.
-
-        See Also
-        --------
-        Index.get_loc : The get_loc method for (single-level) index.
-        MultiIndex.slice_locs : Get slice location given start label(s) and
-                                end label(s).
-        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
-                              sequence of such.
         """
         if method is not None:
             raise NotImplementedError('only the default get_loc method is '
@@ -2470,6 +2470,12 @@ def get_loc_level(self, key, level=0, drop_level=True):
               Element 1: The resulting sliced multiindex/index. If the key
               contains all levels, this will be ``None``.
 
+        See Also
+        --------
+        MultiIndex.get_loc  : Get location for a label or a tuple of labels.
+        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
+                              sequence of such.
+
         Examples
         --------
         >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')],
@@ -2484,12 +2490,6 @@ def get_loc_level(self, key, level=0, drop_level=True):
 
         >>> mi.get_loc_level(['b', 'e'])
         (1, None)
-
-        See Also
-        ---------
-        MultiIndex.get_loc  : Get location for a label or a tuple of labels.
-        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
-                              sequence of such.
         """
 
         def maybe_droplevels(indexer, levels, drop_level):
@@ -2698,7 +2698,7 @@ def get_locs(self, seq):
         locs : array of integers suitable for passing to iloc
 
         Examples
-        ---------
+        --------
         >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')])
 
         >>> mi.get_locs('b')

pandas/core/indexes/period.py

@@ -144,6 +144,14 @@ class PeriodIndex(DatetimeIndexOpsMixin, Int64Index, PeriodDelegateMixin):
     strftime
     to_timestamp
 
+    See Also
+    --------
+    Index : The base pandas Index type.
+    Period : Represents a period of time.
+    DatetimeIndex : Index with datetime64 data.
+    TimedeltaIndex : Index of timedelta64 data.
+    period_range : Create a fixed-frequency PeriodIndex.
+
     Notes
     -----
     Creating a PeriodIndex based on `start`, `periods`, and `end` has
@@ -152,14 +160,6 @@ class PeriodIndex(DatetimeIndexOpsMixin, Int64Index, PeriodDelegateMixin):
     Examples
     --------
     >>> idx = pd.PeriodIndex(year=year_arr, quarter=q_arr)
-
-    See Also
-    ---------
-    Index : The base pandas Index type.
-    Period : Represents a period of time.
-    DatetimeIndex : Index with datetime64 data.
-    TimedeltaIndex : Index of timedelta64 data.
-    period_range : Create a fixed-frequency PeriodIndex.
     """
     _typ = 'periodindex'
     _attributes = ['name', 'freq']

pandas/core/indexes/timedeltas.py

@@ -131,7 +131,7 @@ class TimedeltaIndex(DatetimeIndexOpsMixin, dtl.TimelikeOps, Int64Index,
     to_frame
 
     See Also
-    ---------
+    --------
     Index : The base pandas Index type.
     Timedelta : Represents a duration between two dates or times.
     DatetimeIndex : Index of datetime64 data.

pandas/core/indexing.py

@@ -670,8 +670,8 @@ def _align_series(self, indexer, ser, multiindex_indexer=False):
             a `pd.MultiIndex`, to avoid unnecessary broadcasting.
 
 
-        Returns:
-        --------
+        Returns
+        -------
         `np.array` of `ser` broadcast to the appropriate shape for assignment
         to the locations selected by `indexer`