Add versiondeprecated admonition

[stephenfin]

Purpose

For consistency with other version* admonitions. While the deprecated admonition is marked as deprecated itself in the docs, we do not do anything at runtime since there is almost zero cost to keeping this relative to the work needed for millions of documents to be updated.

All our own uses of this admonition are switched, with some changed to versionchanged where that makes more sense (typically because an attribute or aspect of a feature was deprecated but not the whole feature itself).

References

• <...>
• <...>
• <...>

[timhoffm]

Is this really worth it? Yes, consistency is nice, but I’ve used all these directives and I’ve never stumbled on the naming; .. deprecated:: felt quite natural to me. I actually find .. versiondeprecated:: harder to read and type.

If this is added, I’d at least not deprecate deprecated. Instead, keep both, either as equivalent, or with a recommendation for one. Announcing that deprecated is deprecated will push users into updating because it implies that it will be removed in the future, and I think we should not burden users with this. If you instead state a preference only, new code will use it. Since deprecated statements will by-design be removed after some time, code bases will evolve naturally into the new state, and then deprecating deprecated at some point in the future has much smaller effect.

[stephenfin]

Is this really worth it? Yes, consistency is nice, but I’ve used all these directives and I’ve never stumbled on the naming; .. deprecated:: felt quite natural to me. I actually find .. versiondeprecated:: harder to read and type.

Is it needed? No. But it's helpful to have the set of versionadded, versionchanged, and versionremoved. An alternative would be to provide added, changed, and removed aliases (or introduce hyphens to all).

If this is added, I’d at least not deprecate deprecated. Instead, keep both, either as equivalent, or with a recommendation for one. Announcing that deprecated is deprecated will push users into updating because it implies that it will be removed in the future, and I think we should not burden users with this. If you instead state a preference only, new code will use it. Since deprecated statements will by-design be removed after some time, code bases will evolve naturally into the new state, and then deprecating deprecated at some point in the future has much smaller effect.

I agree. That's my intention in only noting it in the docs: I specifically did not want to create busy work for people.

[AA-Turner]

I'd be happy to add alternative forms with a hyphen, we've done this already for various directive options (no-index, etc). Otherwise I'm ambivalent -- the shorter forms (.. addded::) seem cleaner, but the existing ones are clearer about what they describe.

A

[stephenfin]

I'd be happy to add alternative forms with a hyphen, we've done this already for various directive options (no-index, etc). Otherwise I'm ambivalent -- the shorter forms (.. addded::) seem cleaner, but the existing ones are clearer about what they describe.

Sure. Done.