Tick DateOffset Normalize whatsnew entry has an error

[TomAugspurger]

http://pandas-docs.github.io/pandas-docs-travis/whatsnew.html#tick-dateoffset-normalize-restrictions

• These :class: refs don't resolve. We probably need to add offsets to api.rst and update the references to tseries.offsets.Day, etc. ([DOC]: To remove extra `` to match :class: rendering requirements #21586)
• tic = pd.offsets.Hour(n=2, normalize=True) throws an exception.

[jbrockmendel]

The second bulletpoint is exactly the point of #21427. Me messing up the whatsnew is entirely plausible. Happy to fix, but will need some guidance, as I clearly don't understand [something].

[uds5501]

@TomAugspurger considering that normalize = True was supposed to throw an exception according to #21427, isn't the exception desirable?

[TomAugspurger]

If that was the intent, then the .. ipython:: python block needs an :okexcept: so that a warning doesn't bubble up to the doc builder.

We also don't need the tic on its own line, since that just produces

In [4]: tic
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-4-cd137cbd8d43> in <module>()
----> 1 tic

NameError: name 'tic' is not defined

[jorisvandenbossche]

Repeating my comments from the other issue:

In any case, all occurences of this in the docs should be fixed.

But, if this change is needed, it would also be nice if there is a clear alternative provided in the documentation / deprecation message.
And I think we should maybe also consider deprecating this instead of simply changing.

[jorisvandenbossche]

So this is the use case in the docs (from http://pandas.pydata.org/pandas-docs/stable/timeseries.html#dateoffset-objects):

In [124]: day = Day()

In [125]: day.apply(pd.Timestamp('2014-01-01 09:00'))
Out[125]: Timestamp('2014-01-02 09:00:00')

In [126]: day = Day(normalize=True)

In [127]: day.apply(pd.Timestamp('2014-01-01 09:00'))
Out[127]: Timestamp('2014-01-02 00:00:00')

What is the alternative?

[jbrockmendel]

@jorisvandenbossche good catch, I missed that point in the docs.

The alternative is:

In [123] ts = pd.Timestamp('2014-01-01 09:00')

In [124]: day = Day()

In [127]: day.apply(ts.normalize())
Out [127]: Timestamp('2014-01-02 00:00:00')

[jorisvandenbossche]

OK, that's a good alternative (only for the Hour example, the normalize needs to go after the apply, I think?).
Can you do a PR to update the docs and deprecation message?

[jbrockmendel]

Can you do a PR to update the docs and deprecation message?

I'll try to get this started over the weekend.

[jbrockmendel]

Looking at timeseries.rst the only example with normalize=True is Day. If we edit that to disallow normalize, we'll need to add another non-Tick example where normalize is allowed. How verbose do we want this section to be?

It may also be worth resolving #20633 before spending too much time re-writing these docs.

[jreback]

is this still open?

[TomAugspurger]

Yes, I think so.

[jbrockmendel]

@TomAugspurger still open? if it was really a blocker for 0.24.0, then I'd imagine it must have been fixed

[jorisvandenbossche]

The errors in the docs itself have been fixed in 1986dbe and a03d953

My previous comment about that it would have been nicer to deprecate instead of break this, that ship has sailed ;).
It would still be nice to include the alternative in the whatsnew docs though.

[jbrockmendel]

Last comment suggests the doc issue has been fixed and the remaining question was about whether to do something as a deprecation or not. Since that was from 2019, i think that ship has sailed. Is this closable?