Add unobtrusive deprecation note to the first line of the docstring #12738
Conversation
|
Do we want this for 3.0.x docs? If so, we have to additionally backport #12736. |
|
I found this confusing. Is it possible to do something like “Yet another arrow class (Deprecated)”? I wasn’t sure if the second phrase was meant to be the alternative or not. |
Likely yes, though we have would have to put a bit more work in. The first sentence could be multi-line, so you have to parse the old doc and insert the code at the right place. Also, there are some docstrings, which end with Feel free to push changes. Alternatively, would it already help your understanding if we add any sort of parentheses to the leading "Deprecated"? |
|
Yeah that’s too much bother. It’s not that hard to read. If it were just up to me, I’d do “[Deprecated] Yet another....” but it’s not that big a deal. |
0c7bc72 to
313f653
Compare
|
Square brackets added.
|
|
Merged - think this looks good. OTOH if someone objects to the exact form, we can revisit.... |
PR Summary
As suggested in #12736 (review), this PR adds an unobtrusive "Deprecated." to the beginning of the docstring.
This is intended particularly for the summary.
A maybe slightly unwanted side-effect is that this is of course also present in the docstring, which is a duplication with the more verbose deprecation note.
However, every other way of adding such a not to the summary is far more complicated. It would have to happen within
autosummary, which has to be patched or extended for that functionality. Also for a universal extension ofautosummary, there would be the problem of detecting a deprecated method. So overall, the solution presented here is preferable due to its simplicity.