gh-108514: Add config & 8000 transform to hide old versionmodified in docs #108522
Conversation
|
Thanks for writing this implementation up, I agree it's good to reduce visual clutter for readers. I do have a slight hesitation on doing this though, due to previously poorly written documentation that assumes the For example:
This list created by opening some random pages in the library reference and just searching Perhaps to keep this work we could hide iff the directive has only one argument (the version)? A |
|
@AA-Turner Great point; thanks for the detailed examples! Yeah, that information beyond just mention of the change itself should be moved into the prose, but we certainly wouldn't want to lose it in the meantime, so yeah a heuristic like that would likely be necessary particularly at first, at least if we implemented a higher minimum version than the current status quo of 3.0. It should be fairly easy assuming the inner content node structure is consistent over invocations (inline vs. block content) and Sphinx versions (i.e. just checking that the node has a single para with a single inline node). However, that would be a lot easier and more reliable with the approach below (which could just set a node attribute on directive execution). Aside from just going through all the directive usages and fixing them, I've already been working on factoring the options/functionality common to all |
|
@CAM-Gerlach Do you think this will move forward? Or should it be closed. Thanks! |
|
The topic of visual clutter from 10+ year old change notifications came up again in a recent discussion. The concern raised above about info that only exists in the version changed notices still applies, though. |
As discussed in #108514 and previously among the core devs, there was some amount of interest in hiding versionadded/versionchanged annotations in the Python docs for old versions of Python. Some favored showing all annotations back to the first feature release of the current major version (3.0), which is currently the case in practice as pre-3.0 annotations were completely removed from the source. Others preferred hiding those for older, long-EOL feature releases, e.g. as recent as a 3.6 minimum.
Whatever approach is decided upon, it seems useful to have the ability to specify a minimum version above which to show versionmodified annotations to implement it—even if its 3.0 for now, so its trivial to change in the future if we release a new major version, the older 3.x versions get too long in the tooth, or our policy evolves.
I used an example version of 3.6 to better demonstrate the effect, but marked this as draft/Do-Not-Merge until a minimum version is decided (with 3.0 being the status quo fallback by default).
.. versionadded|.. versionchanged? #108514📚 Documentation preview 📚: https://cpython-previews--108522.org.readthedocs.build/