Repository navigation
DOC/DEPR: consider updating deprecation guidelines to recommend keeping documentation for deprecated, moved, and removed APIs #18852
Description
There have been recent discussions around the CPython documentation1, where users complained that it was difficult to navigate documentation when you're looking specifically for something that was removed; especially because you can't always guess it's been removed between the time the code you're reading was written and the time you're readings docs.
This is caused by the common practice of completely removing documentation when deprecation cycles are ended, and functionalities are removed. Within this perspective, it would be helpful if the documentation was allowed to outlive the functionality, so it's always searchable. Of course this can only be done in the general case provided two preliminary conditions
- we have special rst directives to make deprecated example not run in docs builds (if an output needs to be presented, it should be preserved as a static render)
- current status (deprecated, removed) and timeline (version of deprecation and removal) would need to appear clearly on the rendered docs, in addition to making it obvious that the functionality is entirely discouraged or unusable (for instance using colorful boxes)
Essentially, this needs to be supported by infrastructure.
pytest-doctest-plus would be an obvious candidate to upstream these functionalities to.
related to #8651
this also came out in discussing #18800
Footnotes
-
My initial attempt to find the source back wasn't fruitful. I can spend more time looking for it if requested but to some extent it's not actually crucial to the point I'm making, so I'll make do without it. ↩
Activity
pllim commentedon Nov 10, 2025
I think the general idea was to remove deprecated usage from user-facing examples, to prevent them copy-pasting something we discourage. For dev-facing docs, it can stay but has to be marked clearly as deprecated; still you want anything that people will blindly copy paste to not have deprecated stuff. Hope this clarifies the matter.
pllim commentedon Nov 10, 2025
New directive is probably overkill. If people insist on having deprecated code in example, we can say such-and-such is deprecated, and then link to examples from doc from an older release.
neutrinoceros commentedon Nov 10, 2025
yes, agreed examples should not contain deprecated code. This issue is mostly about API docs.
pllim commentedon Nov 10, 2025
I don't grok the cosmology code. Traditionally, one tends to add a
.. deprecateddirective to the thingy being deprecated, so it still appear in docstring (not necessarily the signature due to our decorators); but not necessarily any examples using it.I hope that makes sense.
neutrinoceros commentedon Nov 10, 2025
And in that spirit, what I'm suggested is to have a
.. removeddirective so removed stuff stays documented forever (or is it.. versionchanged: ...\n removed?)pllim commentedon Nov 10, 2025
I am lost at keeping removed API. Our deprecation period should be long enough to not have to do this.
neutrinoceros commentedon Nov 10, 2025
I would argue it cannot be long enough; some code stays idle without runs or updates for years. How else can we guarantee that stuff remains searchable ?
pllim commentedon Nov 10, 2025
We can add a note that says such-and-such was removed in version this-and-that and then point to old doc.
pllim commentedon Nov 10, 2025
Keeping things we do not support anymore is too much burden for no benefit.
neutrinoceros commentedon Nov 10, 2025
that is basically what I meant to suggest, no more, no less.
pllim commentedon Nov 10, 2025
I want to add that it should be done on a case-by-case basis, not as a general policy. Removed code that is so impactful is quite rare and is usually in really old subpackage, like FITS.