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.