DOC: update groupby/v0.14.0 docs for nth

Author: jreback

doc/source/groupby.rst

@@ -400,6 +400,8 @@ index are the group names and whose values are the sizes of each group.
    for example: ``mean, sum, size, count, std, var, describe, first, last, nth, min, max``. This is
    what happens when you do for example ``DataFrame.sum()`` and get back a ``Series``.
 
+   ``nth`` can act as a reducer *or* a filter, see :ref:`here <groupby.nth>`
+
 .. _groupby.aggregate.multifunc:
 
 Applying multiple functions at once
@@ -855,19 +857,25 @@ This shows the first or last n rows from each group.
 Taking the nth row of each group
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To select from a DataFrame or Series the nth item, use the nth method:
+To select from a DataFrame or Series the nth item, use the nth method. This is a reduction method, and will return a single row (or no row) per group:
 
 .. ipython:: python
 
-   DataFrame([[1, np.nan], [1, 4], [5, 6]], columns=['A', 'B'])
+   df = DataFrame([[1, np.nan], [1, 4], [5, 6]], columns=['A', 'B'])
    g = df.groupby('A')
-   g.nth(0)
 
-   g.nth(1)
+   # nth(0) is the same as g.first()
+   g.nth(0)
+   g.first()
 
+   # nth(-1) is the same as g.last()
    g.nth(-1)
+   g.last()
+
+   # return the nth item
+   g.nth(1)
 
-If you want to select the nth not-null method, use the dropna kwarg. For a DataFrame this should be either 'any' or 'all' just like you would pass to dropna, for a Series this just needs to be truthy.
+If you want to select the nth not-null method, use the ``dropna`` kwarg. For a DataFrame this should be either ``'any'`` or ``'all'`` just like you would pass to dropna, for a Series this just needs to be truthy.
 
 .. ipython:: python
 
@@ -877,9 +885,15 @@ If you want to select the nth not-null method, use the dropna kwarg. For a DataF
 
    g.B.nth(0, dropna=True)
 
-.. warning::
+As with other methods, passing ``as_index=False``, will achieve a filtration, which returns the grouped row.
+
+.. ipython:: python
 
-   Before 0.14.0 this method existed but did not work correctly on DataFrames. The API has changed so that it filters by default, but the old behaviour (for Series) can be achieved by passing dropna. An alternative is to dropna before doing the groupby.
+   df = DataFrame([[1, np.nan], [1, 4], [5, 6]], columns=['A', 'B'])
+   g = df.groupby('A',as_index=False)
+
+   g.nth(0)
+   g.nth(-1)
 
 Enumerate group items
 ~~~~~~~~~~~~~~~~~~~~~

doc/source/v0.14.0.txt

@@ -221,17 +221,31 @@ More consistent behaviour for some groupby methods:
 
      g[['B']].head(1)
 
-- groupby ``nth`` now filters by default, with optional dropna argument to ignore
-  NaN (to replicate the previous behaviour.), See :ref:`the docs <groupby.nth>`.
+- groupby ``nth`` now reduces by default; filtering can be achieved by passing ``as_index=False``. With an optional ``dropna`` argument to ignore
+  NaN. See :ref:`the docs <groupby.nth>`.
+
+  Reducing
 
   .. ipython:: python
 
      df = DataFrame([[1, np.nan], [1, 4], [5, 6]], columns=['A', 'B'])
      g = df.groupby('A')
      g.nth(0)  # can also use negative ints
 
+     # this is equivalent to g.first()
      g.nth(0, dropna='any')  # similar to old behaviour
 
+     # this is equivalent to g.last()
+     g.nth(-1, dropna='any')
+
+  Filtering
+
+  .. ipython:: python
+
+     gf = df.groupby('A',as_index=False)
+     gf.nth(0)
+     gf.nth(0, dropna='any')
+
 - groupby will now not return the grouped column for non-cython functions (:issue:`5610`, :issue:`5614`, :issue:`6732`),
   as its already the index