Refactored _doc_template to _common_see_also and used with the substitution decorator in docstrings where commonly repeated.

Author: benjaminr

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,7 +1079,8 @@ def count(self):
         # defined here for API doc
         raise NotImplementedError
 
-    @Substitution(name='groupby')
+    @Substitution(name='groupby',
+                  see_also=_common_see_also)
     def mean(self, *args, **kwargs):
         """
         Compute mean of groups, excluding missing values.
@@ -1088,11 +1089,7 @@ def mean(self, *args, **kwargs):
         -------
         pandas.Series or pandas.DataFrame
 
-        See Also
-        --------
-        pandas.Series.%(name)s
-        pandas.DataFrame.%(name)s
-        pandas.Panel.%(name)s
+        %(see_also)s
 
         Examples
         --------
@@ -1142,7 +1139,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.
@@ -1163,7 +1160,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.
@@ -1181,7 +1178,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.
@@ -1207,7 +1204,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.
@@ -1223,7 +1220,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.
@@ -1247,7 +1244,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:
@@ -1312,7 +1309,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.
@@ -1441,7 +1438,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.
@@ -1450,7 +1447,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
@@ -1532,7 +1529,8 @@ def backfill(self, limit=None):
         return self._fill('bfill', limit=limit)
     bfill = backfill
 
-    @Substitution(name='groupby')
+    @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
@@ -1551,11 +1549,7 @@ 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
+        %(see_also)s
 
         Examples
         --------
@@ -1818,7 +1812,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):
         """
@@ -1855,7 +1849,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.
@@ -1868,7 +1862,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.
@@ -1881,7 +1875,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.
@@ -1892,7 +1886,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.
@@ -2001,7 +1995,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.
@@ -2024,7 +2018,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):
         """
@@ -2041,19 +2035,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')
+    @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
-        --------
-        pandas.Series.%(name)s
-        pandas.DataFrame.%(name)s
-        pandas.Panel.%(name)s
+        %(see_also)s
 
         Examples
         --------
@@ -2073,19 +2064,16 @@ def head(self, n=5):
         mask = self._cumcount_array() < n
         return self._selected_obj[mask]
 
-    @Substitution(name='groupby')
+    @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
-        --------
-        pandas.Series.%(name)s
-        pandas.DataFrame.%(name)s
-        pandas.Panel.%(name)s
+        %(see_also)s
 
         Examples
         --------