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

ci/code_checks.sh

@@ -213,7 +213,7 @@ fi
 if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
     MSG='Validate docstrings (GL09, GL06, SS04, PR03, PR05, EX04)' ; echo $MSG
-    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL09,GL06,SS04,PR03,PR05,EX04
+    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL09,GL06,GL07,SS04,PR03,PR05,EX04
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/core/frame.py

@@ -6037,7 +6037,7 @@ def _gotitem(self,
         # TODO: _shallow_copy(subset)?
         return subset[key]
 
-    _agg_doc = dedent("""
+    _agg_see_also_doc = dedent("""
     The aggregation operations are always performed over an axis, either the
     index (default) or the column axis. This behavior is different from
     `numpy` aggregation functions (`mean`, `median`, `prod`, `sum`, `std`,
@@ -6047,6 +6047,19 @@ def _gotitem(self,
 
     `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.
+    """)
+
+    _agg_examples_doc = dedent("""
     Examples
     --------
     >>> df = pd.DataFrame([[1, 2, 3],
@@ -6078,23 +6091,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(_shared_docs['aggregate'].format(
+        see_also=_agg_see_also_doc,
+        examples=_agg_examples_doc
+    ) % dict(versionadded='.. versionadded:: 0.20.0', **_shared_doc_kwargs))
     def aggregate(self, func, axis=0, *args, **kwargs):
         axis = self._get_axis_number(axis)
 

pandas/core/generic.py

@@ -6,6 +6,7 @@
 import operator
 import warnings
 import weakref
+from textwrap import dedent
 
 import numpy as np
 
@@ -4895,7 +4896,7 @@ def sample(self, n=None, frac=None, replace=False, weights=None,
     def pipe(self, func, *args, **kwargs):
         return com._pipe(self, func, *args, **kwargs)
 
-    _shared_docs['aggregate'] = ("""
+    _shared_docs['aggregate'] = dedent("""
     Aggregate using one or more operations over the specified axis.
 
     %(versionadded)s
@@ -4926,11 +4927,15 @@ def pipe(self, func, *args, **kwargs):
         if Series.agg is called with single function, returns a scalar
         if Series.agg is called with several functions, returns a Series
 
+    {see_also}
+
     Notes
     -----
     `agg` is an alias for `aggregate`. Use the alias.
 
     A passed user-defined-function will be passed a Series for evaluation.
+
+    {examples}
     """)
 
     _shared_docs['transform'] = ("""

pandas/core/groupby/generic.py

@@ -1246,7 +1246,15 @@ class DataFrameGroupBy(NDFrameGroupBy):
 
     _block_agg_axis = 1
 
-    _agg_doc = dedent("""
+    _agg_see_also_doc = dedent("""
+    See Also
+    --------
+    pandas.DataFrame.groupby.apply
+    pandas.DataFrame.groupby.transform
+    pandas.DataFrame.aggregate
+    """)
+
+    _agg_examples_doc = dedent("""
     Examples
     --------
 
@@ -1294,16 +1302,12 @@ 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(
+    @Appender(_shared_docs['aggregate'].format(
+        see_also=_agg_see_also_doc,
+        examples=_agg_examples_doc
+    ) % dict(
         klass='DataFrame',
         versionadded='',
         axis=''))

pandas/core/groupby/groupby.py

@@ -41,7 +41,7 @@ class providing the base-class of operations.
 from pandas.core.series import Series
 from pandas.core.sorting import get_group_index_sorter
 
-_doc_template = """
+_common_see_also = """
         See Also
         --------
         pandas.Series.%(name)s
@@ -1044,7 +1044,7 @@ def result_to_bool(result):
                                            val_test=val_test, skipna=skipna)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def any(self, skipna=True):
         """
         Returns True if any value in the group is truthful, else False.
@@ -1057,7 +1057,7 @@ def any(self, skipna=True):
         return self._bool_agg('any', skipna)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def all(self, skipna=True):
         """
         Returns True if all values in the group are truthful, else False.
@@ -1070,7 +1070,7 @@ def all(self, skipna=True):
         return self._bool_agg('all', skipna)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def count(self):
         """
         Compute count of group, excluding missing values.
@@ -1079,8 +1079,7 @@ def count(self):
         # defined here for API doc
         raise NotImplementedError
 
-    @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Substitution(name='groupby', see_also=_common_see_also)
     def mean(self, *args, **kwargs):
         """
         Compute mean of groups, excluding missing values.
@@ -1089,6 +1088,8 @@ def mean(self, *args, **kwargs):
         -------
         pandas.Series or pandas.DataFrame
 
+        %(see_also)s
+
         Examples
         --------
         >>> df = pd.DataFrame({'A': [1, 1, 2, 1, 2],
@@ -1137,7 +1138,7 @@ def mean(self, *args, **kwargs):
                 return self._python_agg_general(f)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def median(self, **kwargs):
         """
         Compute median of groups, excluding missing values.
@@ -1158,7 +1159,7 @@ def f(x):
                 return self._python_agg_general(f)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def std(self, ddof=1, *args, **kwargs):
         """
         Compute standard deviation of groups, excluding missing values.
@@ -1176,7 +1177,7 @@ def std(self, ddof=1, *args, **kwargs):
         return np.sqrt(self.var(ddof=ddof, **kwargs))
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def var(self, ddof=1, *args, **kwargs):
         """
         Compute variance of groups, excluding missing values.
@@ -1202,7 +1203,7 @@ def var(self, ddof=1, *args, **kwargs):
                 return self._python_agg_general(f)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def sem(self, ddof=1):
         """
         Compute standard error of the mean of groups, excluding missing values.
@@ -1218,7 +1219,7 @@ def sem(self, ddof=1):
         return self.std(ddof=ddof) / np.sqrt(self.count())
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def size(self):
         """
         Compute group sizes.
@@ -1242,7 +1243,7 @@ def groupby_function(name, alias, npfunc,
             _local_template = "Compute %(f)s of group values"
 
             @Substitution(name='groupby', f=name)
-            @Appender(_doc_template)
+            @Appender(_common_see_also)
             @Appender(_local_template)
             def f(self, **kwargs):
                 if 'numeric_only' not in kwargs:
@@ -1307,7 +1308,7 @@ def last(x):
                                     numeric_only=False)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def ohlc(self):
         """
         Compute sum of values, excluding missing values.
@@ -1436,7 +1437,7 @@ def resample(self, rule, *args, **kwargs):
         return get_resampler_for_grouping(self, rule, *args, **kwargs)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def rolling(self, *args, **kwargs):
         """
         Return a rolling grouper, providing rolling functionality per group.
@@ -1445,7 +1446,7 @@ def rolling(self, *args, **kwargs):
         return RollingGroupby(self, *args, **kwargs)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def expanding(self, *args, **kwargs):
         """
         Return an expanding grouper, providing expanding
@@ -1527,8 +1528,7 @@ def backfill(self, limit=None):
         return self._fill('bfill', limit=limit)
     bfill = backfill
 
-    @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Substitution(name='groupby', see_also=_common_see_also)
     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 +1547,8 @@ 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)s
+
         Examples
         --------
 
@@ -1808,7 +1810,7 @@ def cumcount(self, ascending=True):
             return Series(cumcounts, index)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def rank(self, method='average', ascending=True, na_option='keep',
              pct=False, axis=0):
         """
@@ -1845,7 +1847,7 @@ def rank(self, method='average', ascending=True, na_option='keep',
                                       na_option=na_option, pct=pct, axis=axis)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def cumprod(self, axis=0, *args, **kwargs):
         """
         Cumulative product for each group.
@@ -1858,7 +1860,7 @@ def cumprod(self, axis=0, *args, **kwargs):
         return self._cython_transform('cumprod', **kwargs)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def cumsum(self, axis=0, *args, **kwargs):
         """
         Cumulative sum for each group.
@@ -1871,7 +1873,7 @@ def cumsum(self, axis=0, *args, **kwargs):
         return self._cython_transform('cumsum', **kwargs)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def cummin(self, axis=0, **kwargs):
         """
         Cumulative min for each group.
@@ -1882,7 +1884,7 @@ def cummin(self, axis=0, **kwargs):
         return self._cython_transform('cummin', numeric_only=False)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def cummax(self, axis=0, **kwargs):
         """
         Cumulative max for each group.
@@ -1991,7 +1993,7 @@ def _get_cythonized_result(self, how, grouper, aggregate=False,
             return self._wrap_transformed_output(output)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def shift(self, periods=1, freq=None, axis=0):
         """
         Shift each group by periods observations.
@@ -2014,7 +2016,7 @@ def shift(self, periods=1, freq=None, axis=0):
                                            periods=periods)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Appender(_common_see_also)
     def pct_change(self, periods=1, fill_method='pad', limit=None, freq=None,
                    axis=0):
         """
@@ -2031,15 +2033,16 @@ def pct_change(self, periods=1, fill_method='pad', limit=None, freq=None,
         shifted = fill_grp.shift(periods=periods, freq=freq)
         return (filled / shifted) - 1
 
-    @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Substitution(name='groupby', see_also=_common_see_also)
     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)s
+
         Examples
         --------
 
@@ -2058,15 +2061,16 @@ def head(self, n=5):
         mask = self._cumcount_array() < n
         return self._selected_obj[mask]
 
-    @Substitution(name='groupby')
-    @Appender(_doc_template)
+    @Substitution(name='groupby', see_also=_common_see_also)
     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)s
+
         Examples
         --------