DOC: update pandas.core.groupby.DataFrameGroupBy.resample docstring.
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
########## Docstring (pandas.core.groupby.DataFrameGroupBy.resample)  ##########
################################################################################

Provide resampling when using a TimeGrouper.

Given a grouper the function resamples it according to a string
"string" -> "frequency".

See the :ref:`frequency aliases <timeseries.offset-aliases>`
documentation for more details.

Parameters
----------
rule : str or Offset
    The offset string or object representing target grouper conversion.
*args, **kwargs : [closed, label, loffset]
    For compatibility with other groupby methods. See below for some
    example parameters.
closed : {‘right’, ‘left’}
    Which side of bin interval is closed.
label : {‘right’, ‘left’}
    Which bin edge label to label bucket with.
loffset : timedelta
    Adjust the resampled time labels.

Returns
-------
Grouper
    Return a new grouper with our resampler appended.

Examples
--------
Start by creating a length-4 DataFrame with minute frequency.

>>> idx = pd.date_range('1/1/2000', periods=4, freq='T')
>>> df = pd.DataFrame(data=4 * [range(2)],
...                   index=idx,
...                   columns=['a', 'b'])
>>> df.iloc[2, 0] = 5
>>> df
                     a  b
2000-01-01 00:00:00  0  1
2000-01-01 00:01:00  0  1
2000-01-01 00:02:00  5  1
2000-01-01 00:03:00  0  1

Downsample the DataFrame into 3 minute bins and sum the values of
the timestamps falling into a bin.

>>> df.groupby('a').resample('3T').sum()
                         a  b
a
0   2000-01-01 00:00:00  0  2
    2000-01-01 00:03:00  0  1
5   2000-01-01 00:00:00  5  1

Upsample the series into 30 second bins.

>>> df.groupby('a').resample('30S').sum()
                         a  b
a
0   2000-01-01 00:00:00  0  1
    2000-01-01 00:00:30  0  0
    2000-01-01 00:01:00  0  1
    2000-01-01 00:01:30  0  0
    2000-01-01 00:02:00  0  0
    2000-01-01 00:02:30  0  0
    2000-01-01 00:03:00  0  1
5   2000-01-01 00:02:00  5  1

Resample by month. Values are assigned to the month of the period.

>>> df.groupby('a').resample('M').sum()
                a  b
a
0   2000-01-31  0  3
5   2000-01-31  5  1

Downsample the series into 3 minute bins as above, but close the right
side of the bin interval.

>>> df.groupby('a').resample('3T', closed='right').sum()
                         a  b
a
0   1999-12-31 23:57:00  0  1
    2000-01-01 00:00:00  0  2
5   2000-01-01 00:00:00  5  1

Downsample the series into 3 minute bins and close the right side of
the bin interval, but label each bin using the right edge instead of
the left.

>>> df.groupby('a').resample('3T', closed='right', label='right').sum()
                         a  b
a
0   2000-01-01 00:00:00  0  1
    2000-01-01 00:03:00  0  2
5   2000-01-01 00:03:00  5  1

Add an offset of twenty seconds.

>>> df.groupby('a').resample('3T', loffset='20s').sum()
                         a  b
a
0   2000-01-01 00:00:20  0  2
    2000-01-01 00:03:20  0  1
5   2000-01-01 00:00:20  5  1


See also
--------
pandas.Series.groupby
pandas.DataFrame.groupby
pandas.Panel.groupby

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Use only one blank line to separate sections or paragraphs
	Errors in parameters section
		Parameters {'args', 'kwargs'} not documented
		Unknown parameters {'*args, **kwargs', 'loffset', 'label', 'closed'}
```

args and kwargs are described with asterisks as requested, even if the validator does not recognizes it.

`See also` complains of duplication if left as in the commit in the docstring. Not showed above.  

Labels:
name: Docs
name: Resample
description: resample method

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20374?src=pr&el=h1) Report
> Merging [#20374](https://codecov.io/gh/pandas-dev/pandas/pull/20374?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/fe52d9f29416dd7d19c04ba7d47434b68c411bbd?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20374/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/20374?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20374      +/-   ##
==========================================
- Coverage   92.24%   92.24%   -0.01%     
==========================================
  Files         161      161              
  Lines       51318    51317       -1     
==========================================
- Hits        47339    47338       -1     
  Misses       3979     3979
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.63% <ø> (-0.01%)` | :arrow_down: |
| #single | `42.3% <ø> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20374?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/groupby/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/20374/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9ncm91cGJ5LnB5) | `96.5% <ø> (-0.01%)` | :arrow_down: |
| [pandas/core/dtypes/common.py](https://codecov.io/gh/pandas-dev/pandas/pull/20374/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2NvbW1vbi5weQ==) | `94.37% <0%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20374?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20374?src=pr&el=footer). Last update [fe52d9f...f375ceb](https://codecov.io/gh/pandas-dev/pandas/pull/20374?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

```
################################################################################
########### Docstring (pandas.core.groupby.groupby.GroupBy.resample) ###########
################################################################################

Provide resampling when using a TimeGrouper.

Given a grouper the function resamples it according to a string
"string" -> "frequency".

See the :ref:`frequency aliases <timeseries.offset-aliases>`
documentation for more details.

Parameters
----------
rule : str or Offset
    The offset string or object representing target grouper conversion.
*args, **kwargs
    For compatibility with other groupby methods. See below for some
    example parameters.
closed : {‘right’, ‘left’}
    Which side of bin interval is closed.
label : {‘right’, ‘left’}
    Which bin edge label to label bucket with.
loffset : timedelta
    Adjust the resampled time labels.

Returns
-------
Grouper
    Return a new grouper with our resampler appended.

Examples
--------
Start by creating a length-9 DataFrame with minute frequency.

>>> idx = pd.date_range('1/1/2000', periods=9, freq='T')
>>> df = pd.DataFrame(data=9 * [range(4)],
...                   index=idx,
...                   columns=['a', 'b', 'c', 'd'])
>>> df.iloc[6, 0] = 5
>>> df
                     a  b  c  d
2000-01-01 00:00:00  0  1  2  3
2000-01-01 00:01:00  0  1  2  3
2000-01-01 00:02:00  0  1  2  3
2000-01-01 00:03:00  0  1  2  3
2000-01-01 00:04:00  0  1  2  3
2000-01-01 00:05:00  0  1  2  3
2000-01-01 00:06:00  5  1  2  3
2000-01-01 00:07:00  0  1  2  3
2000-01-01 00:08:00  0  1  2  3

Downsample the DataFrame into 3 minute bins and sum the values of
the timestamps falling into a bin.

>>> df.groupby('a').resample('3T').sum()
                         a  b  c  d
a
0   2000-01-01 00:00:00  0  3  6  9
    2000-01-01 00:03:00  0  3  6  9
    2000-01-01 00:06:00  0  2  4  6
5   2000-01-01 00:06:00  5  1  2  3

Upsample the series into 30 second bins.

>>> df.groupby('a').resample('30S').sum()
                         a  b  c  d
a
0   2000-01-01 00:00:00  0  1  2  3
    2000-01-01 00:00:30  0  0  0  0
    2000-01-01 00:01:00  0  1  2  3
    2000-01-01 00:01:30  0  0  0  0
    2000-01-01 00:02:00  0  1  2  3
    2000-01-01 00:02:30  0  0  0  0
    2000-01-01 00:03:00  0  1  2  3
    2000-01-01 00:03:30  0  0  0  0
    2000-01-01 00:04:00  0  1  2  3
    2000-01-01 00:04:30  0  0  0  0
    2000-01-01 00:05:00  0  1  2  3
    2000-01-01 00:05:30  0  0  0  0
    2000-01-01 00:06:00  0  0  0  0
    2000-01-01 00:06:30  0  0  0  0
    2000-01-01 00:07:00  0  1  2  3
    2000-01-01 00:07:30  0  0  0  0
    2000-01-01 00:08:00  0  1  2  3
5   2000-01-01 00:06:00  5  1  2  3

Resample by month. Values are assigned to the month of the period.

>>> df.groupby('a').resample('M').sum()
                a  b   c   d
a
0   2000-01-31  0  8  16  24
5   2000-01-31  5  1   2   3

Downsample the series into 3 minute bins as above, but close the right
side of the bin interval.

>>> df.groupby('a').resample('3T', closed='right').sum()
                         a  b  c  d
a
0   1999-12-31 23:57:00  0  1  2  3
    2000-01-01 00:00:00  0  3  6  9
    2000-01-01 00:03:00  0  2  4  6
    2000-01-01 00:06:00  0  2  4  6
5   2000-01-01 00:03:00  5  1  2  3

Downsample the series into 3 minute bins and close the right side of
the bin interval, but label each bin using the right edge instead of
the left.

>>> df.groupby('a').resample('3T', closed='right', label='right').sum()
                         a  b  c  d
a
0   2000-01-01 00:00:00  0  1  2  3
    2000-01-01 00:03:00  0  3  6  9
    2000-01-01 00:06:00  0  2  4  6
    2000-01-01 00:09:00  0  2  4  6
5   2000-01-01 00:06:00  5  1  2  3

Add an offset of twenty seconds.

>>> df.groupby('a').resample('3T', loffset='20s').sum()
                         a  b  c  d
a
0   2000-01-01 00:00:20  0  3  6  9
    2000-01-01 00:03:20  0  3  6  9
    2000-01-01 00:06:20  0  2  4  6
5   2000-01-01 00:06:20  5  1  2  3

See Also
--------
pandas.Grouper : specify a frequency to resample with when
    grouping by a key.
DatetimeIndex.resample : Frequency conversion and resampling of
    time series.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Use only one blank line to separate sections or paragraphs
	Errors in parameters section
		Parameters {'args', 'kwargs'} not documented
		Unknown parameters {'loffset', 'label', 'closed', '*args, **kwargs'}
		Parameter "*args, **kwargs" has no type
```
I'm confused about the 'See also' section. It auto-generates the message:
```
See also
--------
pandas.Series.groupby
pandas.DataFrame.groupby
pandas.Panel.groupby
```

With the errors:
	Missing description for See Also "pandas.Series.groupby" reference
	Missing description for See Also "pandas.DataFrame.groupby" reference
	Missing description for See Also "pandas.Panel.groupby" reference

I've replaced it with the commentary noted above in the responses.

Hello @pandres! Thanks for updating the PR.

 - There are no PEP8 issues in the file [`pandas/core/groupby/groupby.py`](https://github.com/pandres/pandas/blob/4b55b5fd51447c43ab380cd7027860994c77bec9/pandas/core/groupby/groupby.py) !


@datapythonista I gave this a read and made some comments, but don't know this section of the code well enough to form an informed opinion.
Thanks @pandres!
Thank you guys!