DOC: Fix pandas.Series.resample docstring
State: closed

- [x] closes #22894
- [x] tests added / passed: 
  - [x] `./scripts/validate_docstrings.py pandas.Series.resample`
  - [x] `flake8 --doctests pandas/core/generic.py`
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry --> Needed?

- Followed pandas docstring [conventions](https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html) and general reST.
- Added deprecation directive on some parameters. Had some doubts but after investigation the recommended API changed after v0.18.0 for these parameters.

Please let me know if I can further improve this.

Thanks!

Labels:
name: Docs

Comments:
Hello @jmrr! Thanks for submitting the PR.

 - There are no PEP8 issues in the file [`pandas/core/generic.py`](https://github.com/jmrr/pandas/blob/49fbd6bf9399438a1df48304044f6b28e1eddbab/pandas/core/generic.py) !


# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23197?src=pr&el=h1) Report
> Merging [#23197](https://codecov.io/gh/pandas-dev/pandas/pull/23197?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/efd1844daaadee29a57943597431611d554b6c4a?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/23197/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/23197?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #23197      +/-   ##
==========================================
- Coverage   92.25%   92.25%   -0.01%     
==========================================
  Files         161      161              
  Lines       51262    51277      +15     
==========================================
+ Hits        47292    47305      +13     
- Misses       3970     3972       +2
```

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

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/23197?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/23197/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.81% <ø> (ø)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/23197/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `86.71% <0%> (-0.08%)` | :arrow_down: |
| [pandas/core/arrays/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/23197/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lbGlrZS5weQ==) | `95.9% <0%> (-0.03%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/23197/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.03% <0%> (ø)` | :arrow_up: |
| [pandas/io/parquet.py](https://codecov.io/gh/pandas-dev/pandas/pull/23197/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhcnF1ZXQucHk=) | `84.76% <0%> (+1.25%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23197?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/23197?src=pr&el=footer). Last update [efd1844...109e414](https://codecov.io/gh/pandas-dev/pandas/pull/23197?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Thanks for the great feedback @datapythonista. I've pushed some changes as per your comments, I've been a bit creative with some examples, let me know if I went too far :) 
Thanks @datapythonista. I've addressed the changes but it's good you highlighted that as these docs are shared between `Series` and `DataFrame` some parameters might accept quite different values depending on the data structure.

Please see my comments and suggestions. Thanks!
@jmrr looks like the error in the CI is in this PR, a non-ascii character somewhere. Can you take a look and leave the CI green, so we can merge?
Sure @datapythonista let me have a look. Thanks for the review!
Looks like it's still failing, but it's an issue with CI setup. The branch is encountering a `pytest` installation that is too new.
That's weird, I think that happened before and it was fixed. Can you merge master into your branch? May be it's based in the old failing version.
Aside from one missing space, LGTM
@jmrr can you run `./scripts/validate_docstrings.py pandas.Series.resample` I think it should capture the error in the indentation (and other formatting problems).

Also, can you remove the `-resample` in the doctests part of `ci/code_checks.sh`? doctests should pass for this now, and we don't need to skip it anymore.
Thanks for the review @jbrockmendel and @datapythonista. Previous to the branch update with latest master, all tests passed when running `./scripts/validate_docstrings.py pandas.Series.resample`.

Now after the update I encountered some errors, but they're `flake8` ones. In particular:

```
2 Errors found:
        flake8 error: E302 expected 2 blank lines, found 0
        flake8 error: E305 expected 2 blank lines after class or function definition, found 0
```

I spent some time looking but I think this validation is trying to lint the example code as if this wasn't REPL code. For instance, the `E302` disappears if I trick the linter with:

```
        >>>
        ...
        ... def custom_resampler(array_like):
        ...     return np.sum(array_like) + 5
        ...
        ...
        ...
        >>> series.resample('3T').apply(custom_resampler)
```

So there's two lines before a function.

Should I spend some time with this and commit the change or this is something that will get improved with time (e.g. by ignoring that error code).

Not sure what's the best solution here, but the problem is in how we validate flake8, we surely don't want to leave blank lines that way in here.

We'll address that in a separate PR in any case.

Thanks for the work on this @jmrr 

CC: @alimcmaster1