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

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

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