Adding (DEPRECATED) prefix to deprecated objects summary in the documentation

[datapythonista]

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

In #18934, @jorisvandenbossche pointed out that replacing a "manual" DEPRECATED comment at the beginning of the docstrings by the .. deprecated:: sphinx directive had a drawback: in the summary pages of the documentation, it doesn't show that the method is deprecated anymore.

This PR shows a way (there are surely others) of using the sphinx directive to add the DEPRECATED prefix automatically.

So, for example, in a page like https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.html, in the list of methods, if abs was deprecated, instead of the current text (in the right column):

Return an object with absolute value taken–only applicable to objects that are all numeric.

if would show:

(DEPRECATED) Return an object with absolute value taken–only applicable to objects that are all numeric.

Personally I think this way is cleaner than adding the DEPRECATED text to each docstring.

[datapythonista]

I think it wasn't clear in the description. This PR isn't finished and shouldn't be committed, it's just to show the general idea on what could be done. I'll finish if after some discussion this seems like a good approach.

[jreback]

can you post a screen shot of the new version? (just a sample where we have actual deprecated showing)

[datapythonista]

Sure @jreback , here you have:

The change in this pull request only affects these autosummaries. For the detail page, with the directive it's already shown. But may be we can customize the sphinx template and make it more visible:

[jreback]

on the auto summaries is it possible to just have: [(DEPRECATED) what the function does?]
(e.g. not have the double deprecation thng)

[datapythonista]

Oh, didn't see it. Yes, the idea is what you say, if you check the Series.sortlevel method in the same screenshot, you'll see it. I'll check what's wrong with argmin and argmax, I guess they don't have a description for being deprecated with the deprecate function.

Does it look like a good idea then? It was a proof of concept, as @jorisvandenbossche thought that adding the DEPRECATED word manually could be simpler. If this approach sounds good, I'll finish and fix the PR (it's showing the DEPRECATED word when a parameter is deprecated but not the function/method).

[jreback]

@datapythonista ok, so it was just an issue with that doc-string. that's ok then.

I think if we can (and you show its straightforward) to do this autmatically then that is the best. manually doing things is always error prone. Sure we have to add the deprecated directive, but at least its only one thing we are adding.

[jorisvandenbossche]

Didn't look in detail yet, but a simple '.. deprecated::' in obj.__doc__ won't be enough as this also detects deprecated parameters (although that should be fixable with some extra complexity)

I agree this does look like a nice and rather simple method to fix the autosummary tables (although I personally still think the more 'screaming' DEPRECATED can also be useful for plain text docstrings to users don't miss it, but I won't press on that)

[jorisvandenbossche]

Didn't look in detail yet, but a simple '.. deprecated::' in obj.doc won't be enough as this also detects deprecated parameters (although that should be fixable with some extra complexity)

Ah, I didn't read your last comment in detail as you already mentioned that yourself!

[datapythonista]

Yep, I was aware @jorisvandenbossche.

I just pushed a version that does the right thing (just add the deprecation string if the method is deprecated, not the parameters).

I reviewed argmin and argmax, and as I guessed, they don't have a docstring because they use the deprecate decorator (which includes the deprecated directive to identify the methods from the docstring). So, the result is that the directive is taken as the summary in the autosummary.

Please let me know if the PR looks all right now.

Thanks!

[jreback]

can these imports go at the top?

[datapythonista]

@jreback, the numpydoc import can't be at the very top, because it requires the sphinxext directory to be in the PYTHONPATH. I moved it after the update of sys.path.

[jreback]

@TomAugspurger @jorisvandenbossche ok with this?

[jreback]

@jorisvandenbossche @TomAugspurger

[jreback]

can you rebase

happy to merge this

[datapythonista]

Rebased, thanks!

[jreback]

thanks @datapythonista have a look at the built docs to verify this looks ok

[datapythonista]

Thanks! Looking good: