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

Author: benjaminr

ci/code_checks.sh

@@ -212,8 +212,8 @@ fi
 ### DOCSTRINGS ###
 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
+ MSG='Validate docstrings (GL06, GL07, GL09, SS04, PR03, PR05, EX04)' ; echo $MSG
+ $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,PR03,PR05,EX04
  RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/core/frame.py

@@ -6091,7 +6091,7 @@ def _gotitem(self,
  # TODO: _shallow_copy(subset)?
  return subset[key]
 
- _agg_doc = dedent("""
+ _agg_summary_and_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`,
@@ -6101,6 +6101,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],
@@ -6132,23 +6145,13 @@ 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))
+ @Substitution(see_also=_agg_summary_and_see_also_doc,
+ examples=_agg_examples_doc,
+ versionadded='.. versionadded:: 0.20.0',
+ **_shared_doc_kwargs)
+ @Appender(_shared_docs['aggregate'])
  def aggregate(self, func, axis=0, *args, **kwargs):
  axis = self._get_axis_number(axis)
 

pandas/core/generic.py

@@ -4,6 +4,7 @@
 import gc
 import json
 import operator
+from textwrap import dedent
 import warnings
 import weakref
 
@@ -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)s
+
  Notes
  -----
  `agg` is an alias for `aggregate`. Use the alias.
 
  A passed user-defined-function will be passed a Series for evaluation.
+
+ %(examples)s
  """)
 
  _shared_docs['transform'] = ("""

pandas/core/groupby/generic.py

@@ -706,10 +706,17 @@ def _selection_name(self):
  else:
  return self._selection
 
- _agg_doc = dedent("""
- Examples
+ _agg_see_also_doc = dedent("""
+ See Also
  --------
+ pandas.Series.groupby.apply
+ pandas.Series.groupby.transform
+ pandas.Series.aggregate
+ """)
 
+ _agg_examples_doc = dedent("""
+ Examples
+ --------
  >>> s = pd.Series([1, 2, 3, 4])
 
  >>> s
@@ -733,13 +740,6 @@ def _selection_name(self):
  min max
  1 1 2
  2 3 4
-
- See Also
- --------
- pandas.Series.groupby.apply
- pandas.Series.groupby.transform
- pandas.Series.aggregate
-
  """)
 
  @Appender(_apply_docs['template']
@@ -748,11 +748,12 @@ def _selection_name(self):
  def apply(self, func, *args, **kwargs):
  return super(SeriesGroupBy, self).apply(func, *args, **kwargs)
 
- @Appender(_agg_doc)
- @Appender(_shared_docs['aggregate'] % dict(
- klass='Series',
- versionadded='',
- axis=''))
+ @Substitution(see_also=_agg_see_also_doc,
+ examples=_agg_examples_doc,
+ versionadded='',
+ klass='Series',
+ axis='')
+ @Appender(_shared_docs['aggregate'])
  def aggregate(self, func_or_funcs, *args, **kwargs):
  _level = kwargs.pop('_level', None)
  if isinstance(func_or_funcs, compat.string_types):
@@ -1246,7 +1247,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,19 +1303,14 @@ 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=''))
+ @Substitution(see_also=_agg_see_also_doc,
+ examples=_agg_examples_doc,
+ versionadded='',
+ klass='DataFrame',
+ axis='')
+ @Appender(_shared_docs['aggregate'])
  def aggregate(self, arg, *args, **kwargs):
  return super(DataFrameGroupBy, self).aggregate(arg, *args, **kwargs)