Adding (DEPRECATED) prefix to deprecated objects summary in the documentation
- [ ] closes #xxxx
- [ ] tests added / passed
- [X] 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.