DOC: Fix docstrings with the sections in the wrong order #24280

pandas-dev · jreback · Dec 27, 2018 · Dec 14, 2018 · Dec 14, 2018 · Dec 14, 2018
commit 44469421fb8c1735f7ebecc2de0bb332e7725bbc
diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx
@@ -158,6 +158,29 @@ cdef class Interval(IntervalMixin):
         Whether the interval is closed on the left-side, right-side, both or
         neither. See the Notes for more detailed explanation.
 
+    See Also
+    --------
+    IntervalIndex : An Index of Interval objects that are all closed on the
+        same side.
+    cut : Convert continuous data into discrete bins (Categorical
+        of Interval objects).
+    qcut : Convert continuous data into bins (Categorical of Interval objects)
+        based on quantiles.
+    Period : Represents a period of time.
+    """
+    _typ = "interval"
+
+    cdef readonly object left
+    """Left bound for the interval"""
+
+    cdef readonly object right
+    """Right bound for the interval"""
+
+    cdef readonly str closed
+    """
+    Whether the interval is closed on the left-side, right-side, both or
+    neither
+
     Notes
     -----
     The parameters `left` and `right` must be from the same type, you must be
@@ -226,29 +249,6 @@ cdef class Interval(IntervalMixin):
     >>> volume_1 = pd.Interval('Ant', 'Dog', closed='both')
     >>> 'Bee' in volume_1
     True
-
-    See Also
-    --------
-    IntervalIndex : An Index of Interval objects that are all closed on the
-        same side.
-    cut : Convert continuous data into discrete bins (Categorical
-        of Interval objects).
-    qcut : Convert continuous data into bins (Categorical of Interval objects)
-        based on quantiles.
-    Period : Represents a period of time.
-    """
-    _typ = "interval"
-
-    cdef readonly object left
-    """Left bound for the interval"""
-
-    cdef readonly object right
-    """Right bound for the interval"""
-
-    cdef readonly str closed
-    """
-    Whether the interval is closed on the left-side, right-side, both or
-    neither
     """
 
     def __init__(self, left, right, str closed='right'):
@@ -387,6 +387,11 @@ cdef class Interval(IntervalMixin):
         bool
             ``True`` if the two intervals overlap, e
10000
lse ``False``.
 
+        See Also
+        --------
+        IntervalArray.overlaps : The corresponding method for IntervalArray
+        IntervalIndex.overlaps : The corresponding method for IntervalIndex
+
         Examples
         --------
         >>> i1 = pd.Interval(0, 2)
@@ -409,11 +414,6 @@ cdef class Interval(IntervalMixin):
         >>> i6 = pd.Interval(1, 2, closed='neither')
         >>> i4.overlaps(i6)
         False
-
-        See Also
-        --------
-        IntervalArray.overlaps : The corresponding method for IntervalArray
-        IntervalIndex.overlaps : The corresponding method for IntervalIndex
         """
         if not isinstance(other, Interval):
             msg = '`other` must be an Interval, got {other}'

diff --git a/pandas/_libs/tslibs/timedeltas.pyx b/pandas/_libs/tslibs/timedeltas.pyx
@@ -1059,6 +1059,10 @@ cdef class _Timedelta(timedelta):
         -------
         formatted : str
 
+        See Also
+        --------
+        Timestamp.isoformat
+
         Notes
         -----
         The longest component is days, whose value may be larger than
@@ -1081,10 +1085,6 @@ cdef class _Timedelta(timedelta):
         'P0DT0H0M10S'
         >>> pd.Timedelta(days=500.5).isoformat()
         'P500DT12H0MS'
-
-        See Also
-        --------
-        Timestamp.isoformat
         """
         components = self.components
         seconds = '{}.{:0>3}{:0>3}{:0>3}'.format(components.seconds,
@@ -1210,14 +1210,14 @@ class Timedelta(_Timedelta):
         """
         Round the Timedelta to the specified resolution
 
-        Returns
-        -------
-        a new Timedelta rounded to the given resolution of `freq`
-
         Parameters
         ----------
         freq : a freq string indicating the rounding resolution
 
+        Returns
+        -------
+        a new Timedelta rounded to the given resolution of `freq`
+
         Raises
         ------
         ValueError if the freq cannot be converted

diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx
@@ -776,10 +776,6 @@ class Timestamp(_Timestamp):
         """
         Round the Timestamp to the specified resolution
 
-        Returns
-        -------
-        a new Timestamp rounded to the given resolution of `freq`
-
         Parameters
         ----------
         freq : a freq string indicating the rounding resolution
@@ -802,6 +798,10 @@ class Timestamp(_Timestamp):
 
             .. versionadded:: 0.24.0
 
+        Returns
+        -------
+        a new Timestamp rounded to the given resolution of `freq`
+
         Raises
         ------
         ValueError if the freq cannot be converted

diff --git a/pandas/core/accessor.py b/pandas/core/accessor.py
@@ -201,6 +201,10 @@ def decorator(accessor):
     Name under which the accessor should be registered. A warning is issued
     if this name conflicts with a preexisting attribute.
 
+See Also
+--------
+%(others)s
+
 Notes
 -----
 When accessed, your accessor will be initialized with the pandas object
@@ -250,10 +254,6 @@ def plot(self):
     (5.0, 10.0)
     >>> ds.geo.plot()
     # plots data on a map
-
-See Also
---------
-%(others)s
 """
 
 

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -6046,6 +6046,17 @@ def _gotitem(self,
     axis=0)``.
 
     `agg` is an alias for `aggregate`. Use the alias.
+
+    See Also
+    --------
+    DataFrame.apply : Perform any type of operations.
+    DataFrame.transform : Perform transformation type operations.
+    pandas.core.groupby.GroupBy : Perform operations over groups.
+    pandas.core.resample.Resampler : Perform operations over resampled bins.
+    pandas.core.window.Rolling : Perform operations over rolling window.
+    pandas.core.window.Expanding : Perform operations over expanding window.
+    pandas.core.window.EWM : Perform operation over exponential weighted
+        window.
 
     Examples
     --------
@@ -6078,23 +6089,12 @@ def _gotitem(self,
     2    8.0
     3    NaN
     dtype: float64
-
-    See Also
-    --------
-    DataFrame.apply : Perform any type of operations.
-    DataFrame.transform : Perform transformation type operations.
-    pandas.core.groupby.GroupBy : Perform operations over groups.
-    pandas.core.resample.Resampler : Perform operations over resampled bins.
-    pandas.core.window.Rolling : Perform operations over rolling window.
-    pandas.core.window.Expanding : Perform operations over expanding window.
-    pandas.core.window.EWM : Perform operation over exponential weighted
-        window.
     """)
 
-    @Appender(_agg_doc)
     @Appender(_shared_docs['aggregate'] % dict(
         versionadded='.. versionadded:: 0.20.0',
         **_shared_doc_kwargs))
+    @Appender(_agg_doc)
     def aggregate(self, func, axis=0, *args, **kwargs):
         axis = self._get_axis_number(axis)
 

diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py
@@ -1247,6 +1247,12 @@ class DataFrameGroupBy(NDFrameGroupBy):
     _block_agg_axis = 1
 
     _agg_doc = dedent("""
+    See Also
+    --------
+    pandas.DataFrame.groupby.apply
+    pandas.DataFrame.groupby.transform
+    pandas.DataFrame.aggregate
+
     Examples
     --------
 
@@ -1294,19 +1300,13 @@ class DataFrameGroupBy(NDFrameGroupBy):
     A
     1   1   2  0.590716
     2   3   4  0.704907
-
-    See Also
-    --------
-    pandas.DataFrame.groupby.apply
-    pandas.DataFrame.groupby.transform
-    pandas.DataFrame.aggregate
     """)
 
-    @Appender(_agg_doc)
     @Appender(_shared_docs['aggregate'] % dict(
         klass='DataFrame',
         versionadded='',
         axis=''))
+    @Appender(_agg_doc)
     def aggregate(self, arg, *args, **kwargs):
         return super(DataFrameGroupBy, self).aggregate(arg, *args, **kwargs)
 

diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py
@@ -1080,7 +1080,6 @@ def count(self):
         raise NotImplementedError
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def mean(self, *args, **kwargs):
         """
         Compute mean of groups, excluding missing values.
@@ -1089,6 +1088,12 @@ def mean(self, *args, **kwargs):
         -------
         pandas.Series or pandas.DataFrame
 
+        See Also
+        --------
+        pandas.Series.%(name)s
+        pandas.DataFrame.%(name)s
+        pandas.Panel.%(name)s
+
         Examples
         --------
         >>> df = pd.DataFrame({'A': [1, 1, 2, 1, 2],
@@ -1528,7 +1533,6 @@ def backfill(self, limit=None):
     bfill = backfill
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def nth(self, n, dropna=None):
         """
         Take the nth row from each group if n is an int, or a subset of rows
@@ -1547,6 +1551,12 @@ def nth(self, n, dropna=None):
             apply the specified dropna operation before counting which row is
             the nth row. Needs to be None, 'any' or 'all'
 
+        See Also
+        --------
+        pandas.Series.%(name)s
+        pandas.DataFrame.%(name)s
+        pandas.Panel.%(name)s
+
         Examples
         --------
 
@@ -2032,14 +2042,19 @@ def pct_change(self, periods=1, fill_method='pad', limit=None, freq=None,
         return (filled / shifted) - 1
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def head(self, n=5):
         """
         Returns first n rows of each group.
 
         Essentially equivalent to ``.apply(lambda x: x.head(n))``,
         except ignores as_index flag.
 
+        See Also
+        --------
+        pandas.Series.%(name)s
+        pandas.DataFrame.%(name)s
+        pandas.Panel.%(name)s
+
         Examples
         --------
 
@@ -2059,14 +2074,19 @@ def head(self, n=5):
         return self._selected_obj[mask]
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def tail(self, n=5):
         """
         Returns last n rows of each group.
 
         Essentially equivalent to ``.apply(lambda x: x.tail(n))``,
         except ignores as_index flag.
 
+        See Also
+        --------
+        pandas.Series.%(name)s
+        pandas.DataFrame.%(name)s
+        pandas.Panel.%(name)s
+
         Examples
         --------
 

diff --git a/pandas/core/resample.py b/pandas/core/resample.py
@@ -253,11 +253,11 @@ def pipe(self, func, *args, **kwargs):
     2013-01-01 00:00:04      5       NaN
     """)
 
-    @Appender(_agg_doc)
     @Appender(_shared_docs['aggregate'] % dict(
         klass='DataFrame',
         versionadded='',
         axis=''))
+    @Appender(_agg_doc)
     def aggregate(self, func, *args, **kwargs):
 
         self._set_binner()

diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -3302,10 +3302,10 @@ def _gotitem(self, key, ndim, subset=None):
     dtype: int64
     """)
 
-    @Appender(_agg_doc)
     @Appender(generic._shared_docs['aggregate'] % dict(
         versionadded='.. versionadded:: 0.20.0',
         **_shared_doc_kwargs))
+    @Appender(_agg_doc)
     def aggregate(self, func, axis=0, *args, **kwargs):
         # Validate the axis parameter
         self._get_axis_number(axis)