gh-108514: Add config & transform to hide old versionmodified in docs

[CAM-Gerlach]

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).

• Issue: Policy for removal of old .. versionadded|.. versionchanged ? #108514

---

📚 Documentation preview 📚: https://cpython-previews--108522.org.readthedocs.build/

[AA-Turner]

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 version{added,changed} directives will be read.

For example:

• https://docs.python.org/3/library/_thread.html#thread.lock.acquire (POSIX signal behaviour is not mentioned in the body)
• https://docs.python.org/3/library/datetime.html#technical-detail (Note 6, at the end -- AFAICS the aware timezone behaviour isn't documented elsewhere)
• https://docs.python.org/3/library/functions.html#compile (The prose doesn't mention newline handling)
• https://docs.python.org/3/library/gc.html#gc.garbage (ResourceWarning isn't mentioned in the body)
• https://docs.python.org/3/library/logging.handlers.html#logging.handlers.SysLogHandler.emit (most of the content here is in versionchanged directives)
• https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertAlmostEqual (the verbiage about exact equality)
• https://docs.python.org/3/library/wave.html#wave.Wave_write.setframerate (rounding behaviour)

This list created by opening some random pages in the library reference and just searching Changed in version 3.2: -- more will certainly exist for other versions, and versionadded.

Perhaps to keep this work we could hide iff the directive has only one argument (the version)?

A

[CAM-Gerlach]

@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 versionmodified directives in the enhanced deprecated-removed directive I'm working on into a superclass with compatible usage to the upstream implementation. This would make it easy to add an option to override the default show-hide, as well as control what is shown and hidden by default using much more refined criteria due to the additional structured data, as well as do things like reliably group and sort the entries for a given object by ascending or descending version.

[willingc]

@CAM-Gerlach Do you think this will move forward? Or should it be closed. Thanks!