DOC: update groupby pd.Grouper docs

Author: jreback

doc/source/api.rst

@@ -1193,6 +1193,7 @@ Indexing, iteration
    GroupBy.groups
    GroupBy.indices
    GroupBy.get_group
+   Grouper
 
 Function application
 ~~~~~~~~~~~~~~~~~~~~

doc/source/release.rst

@@ -132,7 +132,7 @@ API Changes
   ``FutureWarning`` is raised  to alert that the old ``rows`` and ``cols`` arguments
   will not be supported in a future release (:issue:`5505`)
 
-- Allow specification of a more complex groupby, via ``pd.Groupby`` (:issue:`3794`)
+- Allow specification of a more complex groupby, via ``pd.Grouper`` (:issue:`3794`)
 
 - A tuple passed to ``DataFame.sort_index`` will be interpreted as the levels of
   the index, rather than requiring a list of tuple (:issue:`4370`)

doc/source/v0.14.0.txt

@@ -94,7 +94,7 @@ These are out-of-bounds selections
 
      g.nth(0, dropna='any')  # similar to old behaviour
 
-- Allow specification of a more complex groupby via ``pd.Groupby``, such as grouping
+- Allow specification of a more complex groupby via ``pd.Grouper``, such as grouping
   by a Time and a string field simultaneously. See :ref:`the docs <groupby.specify>`. (:issue:`3794`)
 
 - Local variable usage has changed in

pandas/core/groupby.py

@@ -141,25 +141,37 @@ def _last(x):
 
 class Grouper(object):
     """
-    A Grouper allows the user to specify a groupby instruction
+    A Grouper allows the user to specify a groupby instruction for a target object
+
+    This specification will select a column via the key parameter, or if the level and/or
+    axis parameters are given, a level of the index of the target object.
+
+    These are local specifications and will override 'global' settings, that is the parameters
+    axis and level which are passed to the groupby itself.
 
     Parameters
     ----------
-    key : groupby key, default None
-    level : name, int level number, default None
-    freq : string / freqency object, default None
-    sort : boolean, whether to sort the resulting labels, default True
+    key : string, defaults to None
+        groupby key, which selects the grouping column of the target
+    level : name/number, defaults to None
+        the level for the target index
+    freq : string / freqency object, defaults to None
+        This will groupby the specified frequency if the target selection (via key or level) is
+        a datetime-like object
+    axis : number/name of the axis, defaults to None
+    sort : boolean, default to False
+        whether to sort the resulting labels
 
     Returns
     -------
     A specification for a groupby instruction
 
     Examples
     --------
-    df.groupby(Group(key='A')) : syntatic sugar for df.groupby('A')
-    df.groupby(Group(key='date',freq='60s')) : specify a resample on the column 'date'
-    df.groupby(Group(level='date',freq='60s',axis=1)) :
-       specify a resample on the level 'date' on the columns axis with a frequency of 60s
+    >>> df.groupby(Grouper(key='A')) : syntatic sugar for df.groupby('A')
+    >>> df.groupby(Grouper(key='date',freq='60s')) : specify a resample on the column 'date'
+    >>> df.groupby(Grouper(level='date',freq='60s',axis=1)) :
+        specify a resample on the level 'date' on the columns axis with a frequency of 60s
 
     """