DOC: Enhance asfreq docs
State: closed

- [n/a] closes #xxxxx
- [x] passes `black pandas`
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] tests added

Enhanced some docstrings for time-series related methods; mainly `asfreq`. Namely:
 - Converted `NDFrame.asfreq` into a template to use the specific `klass` in `Series.asfreq` and `DataFrame.asfreq`
 - Fully explain the behaviour of `NDFrame.asfreq` in the extended summary.
 - Add an extended summary to `asfreq` in `PeriodArray`/`PeriodIndex`
 - Use `klass` kwarg in docstring template for `PeriodAray.asfreq`\`PeriodIndex.asfreq`
 - Add an extended summary to `date_range`
 - Other very minor fixes/enhancements


The original motivator for this PR was [this question](https://stackoverflow.com/q/63860589/6117426), in particular the confusion of the asker.

Labels:
name: Docs
name: Stale

Comments:
Don't merge yet, I've noticed a couple of issues
@MarcoGorelli  Alright, it should be all done now. I've extracted a generic `call_once` context manager (for the warnings thing) to `pandas.util._call_once`, and added tests for that. The two of the CI builds are failing on a completely unrelated test (`tests.plotting.TestDataFrameGroupByPlots.test_series_groupby_plotting_nominally_works`), and I can't for the life of me figure out why.
> The two of the CI builds are failing on a completely unrelated test (`tests.plotting.TestDataFrameGroupByPlots.test_series_groupby_plotting_nominally_works`), and I can't for the life of me figure out why.

They're almost certainly unrelated, don't worry about them

Will take another look later, thanks for updating!
Does this have to all be part of the same PR, or could `check_deprecated_resample_kwargs` be a separate one?
> Does this have to all be part of the same PR, or could `check_deprecated_resample_kwargs` be a separate one?

It has to be part of the same PR because of how the warnings were managed previously: the warnings were raised in `Grouper.__new__`, for all possible paths that led there, and the `stacklevel` was set based on whether the call came from a `TimeGrouper` or not (because at the time, every public call of `resample` ended up at `TimeGrouper` in exactly three stack frames).

https://github.com/pandas-dev/pandas/blob/8df0218a4bfae50a7191ff0869e63c28884fb733/pandas/core/groupby/grouper.py#L227-L268

This is very brittle—as this PR demonstrates. When I made the changes to `resample` docs, I made `NDFrame.resample` into a template, to allow for customized `DataFrame.resample` and `Series.resample` docs. This introduces a new stack frame since these methods have to call `super().resample(...)`: 

https://github.com/pandas-dev/pandas/blob/7e8812318d62278712999f6b8351a237f3a6c582/pandas/core/frame.py#L9127-L9156

This then breaks the hacky `stacklevel` munging mentioned above since now for `DataFrame` and `Series` the `stacklevel` should technically have been `5`.

In fact if you run the tests on commit 27b16cf, you will see that they fail on `pandas.tests.resample.test_deprecated`. Then I added the `check_resample_deprecated_kwargs` thing in e78a415 to fix this issue.
Thanks @plammens for explaining - from what I've understood, you want to share docstrings between `DataFrame.resample` and `Series.resample`. However, this causes problems with how the warnings are managed in `Grouper.__new__`.

Would it be possible to make one PR to change how warnings are managed in `Grouper.__new__`? You write

> This then breaks the hacky stacklevel munging mentioned above

so would it be possible to have 1 PR to improve the stacklevel munging and then, once that's in, another PR to share docstrings between `DataFrame.resample` and `Series.resample`? Sorry if I've misunderstood, in which case please do correct me
> Thanks @plammens for explaining - from what I've understood, you want to share docstrings between `DataFrame.resample` and `Series.resample`. However, this causes problems with how the warnings are managed in `Grouper.__new__`.

Yes, exactly.

I've made a new PR (#36629), but until that gets merged, if I remove the relevant commits from here, this PR will be failing the tests, so should I wait until the other PR gets merged?
> I've made a new PR (#36629),

Awesome, thanks

> so should I wait until the other PR gets merged?

Yup
This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
> This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.

Waiting for #36629 (or an equivalent fix) to be merged.
> > This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
> 
> Waiting for #36629 (or an equivalent fix) to be merged.

why is this a blocker?
> > > This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
> > 
> > 
> > Waiting for #36629 (or an equivalent fix) to be merged.
> 
> why is this a blocker?

As far as I understand, it's because he wants to share docs between `DataFrame.resample` and `Series.resample`, though doing so would change the stacklevel
let just fix the appropriate tests (eg turn off the stack level checks)

these aren't that important for a really old warning
Sure - happy to do that, @plammens ? Sorry for having led you down the wrong path
> let just fix the appropriate tests (eg turn off the stack level checks)
> 
> these aren't that important for a really old warning

There is already an open PR for that - #37603 :)
After discussion in #37603, it was decided to just update the stacklevel accordingly and disable some of the stacklevel checks for those cases in which the stacklevel couldn't be computed easily (at the same time as the one for `Series.resample` and `DataFrame.resample`). I updated the PR to reflect this.

I rebased onto the latest passing master. There have been lots of changes meanwhile, so it is possible I messed up something while resolving merge conflicts.

CC @jorisvandenbossche 
thanks @plammens very nice
pls have a look at the built docs (may take a bit): https://pandas.pydata.org/pandas-docs/dev/ and if needed followup