DOC: Using deprecated sphinx directive instead of non-standard messages in docstrings (#18928)
- [X] closes #18928 
- [X] tests passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

Hello @datapythonista! Thanks for updating the PR.

































Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on January 06, 2018 at 13:55 Hours UTC also would love some tests in contributing.rst on how to depreciate things (e.g. how to use the decorator is prob enough) Thanks for the review @jreback. I updated the pull request, addressing all your comments. Please let me know if there is anything that is not yet clear, or that can be improved.

Regarding the blank line after the directive, it doesn't make a difference for sphinx. In both cases the comment about the deprecation is shown inline. Sure, thanks for the comments @jreback .

I'm also implementing a more exhaustive version of `find_deprecated.py`. I think it makes sense to know your opinion about it before continuing.

What I think it would be useful is to have a script that detects all deprecated stuff, so it can be completely removed at the right time. That's what `find_deprecated` does, but just for methods of `Series`, `DataFrame` and `Panel`, and assuming they got the `.. deprecated::` directive in the docstring.

What I'm implementing now is a version that checks all python files in the project, looks for `FutureWarning`, and checks the docstrings of everything in the file (the module itself, classes, functions,...), and finds what has been deprecated.

This way, if when releasing pandas 0.22, everything that was deprecated before 0.19 needs to go away, it can be detected in an easy and reliable way.

Does this make sense? this would be fine as a double check: https://github.com/pandas-dev/pandas/pull/18934#issuecomment-354168451

We keep a nice annotated list: https://github.com/pandas-dev/pandas/issues/6581
and removals: https://github.com/pandas-dev/pandas/issues/13777

 Ah, thanks for pointing it out. I checked for the list in the code, didn't know it was in github.

Then, I think I'll update the pull request with your comments, removing the find_deprecated.py script. Later on I'll implement the script, probably in a repo separate from pandas (there is nothing pandas specific in it), and run it to see if there is nothing missing in these tickets. @datapythonista that would be great! @jreback fixed items in last review. In lint.sh I added DEPRECATE, DEPRECATED and Deprecated, but only if they finish with colon, comma or dot, as it was capturing DeprecatedModule for example. @jreback, I made the requested changes. I agree that the scripts should be added to a note in the contributing documentation, but I'd do that in a separate request if you agree. That's unrelated to this PR, and some standardization of the scripts will be probably required. So I don't think it's a small change. just needs a rebase and looks ok. Rebased. Thanks @jreback  lgtm. ping on green. @jreback, am I right in assuming that all the stuff deprecated in 0.19 and before can be deleted? If that's the case, I'll submit a PR leaving only the methods and functions with deprecation warning added in 0.20, 0.21 and 0.22. things before 0.19.0 should already be removed (except for - couple of ones) I submittet the PR's to deprecate ``as_matrix``, ``asobject`` and ``valid``. These will be deprecated in 0.23. Currently you've marked them as deprecated in 0.21.1/0.21.2. Thanks for pointing out @topper-123. It looks like I misunderstood something about the git workflow. For `as_matrix` for example, I saw it was merged to master in November 26th, and that 0.21.1 was the next next version released (on December 12), so I assumed everything in master was released, which doesn't seem right.

I'll compare all the versions I added with #6581 and with github tags, and fix the wrong ones.

Thanks for reporting this! @topper-123  I reviewed all the deprecation versions I added, with the release where the commit was introduced (checking `git tag --contains <commit>`). All them should be correct now. I added the version 0.23.0 to the ones that haven't been released. They match the ones you mentioned.

@jreback, this should be ready to be merged now.

Just to let you know, compared to the changes you already reviewed, I removed from the docstring the `Timestamp.offset` attribute in pandas/_libs/tslibs/timestamps.pyx. The attributed was removed from the code in fb95f7f305e85d474cc44283fc642abc900e0096 but not from the docstring. For the rest is the same, with updated deprecation versions.

Thanks to both! thanks @datapythonista very nice! Thanks a lot for you comments @jorisvandenbossche, I see your point, didn't think about it.

My main motivation for standardizing the docstrings is to be able to automatically detect the deprecated methods. The `api_rst_coverage.py` and `list_future_warnings.sh` scripts benefit from it already.

I see two solutions here:
1. Given the fact that now it can easily be detected that a module is deprecated by code, check it while generating api_rst.html and the DataFrame page (I guess this needs to be done in sphinx)
2. Add the DEPRECATED word as the first word in all deprecated methods, besides the `.. deprecated::` directive (which also provides the version)

I prefer 1, as seems the "right" way to do it. Surely more complex to implement now, but looks cleaner once implemented.

What do you think?

For the `NDFrame` in the docstring summary, I think I copied that summary from the called function, and didn't think NDFrame wasn't part of the public API. I'll fix it and send a PR.

Thanks!

 Doing that in sphinx will probably some overkill IMO, so a pragmatic solution is to do both. I don't think that is a problem, as the `.. deprectated::` directive gives then additional information on when it is deprecated. Out of curiosity, how does the `.. deprecated::` macro appear in generated docs? I hope it's highly visible in some way, e.g., a big red box? https://github.com/pandas-dev/pandas/issues/20349