Use hyphenated version directives

[stephenfin]

Purpose

We alias the versioning directives like so:

• version-added (was versionadded)
• version-changed (was versionchanged)
• version-removed (was versionremoved)
• version-deprecated (was deprecated)

The original names are marked as deprecated in the docs but do no produce build-time warnings, since we don't want to break 1000s of builds using -W (warning is error) over this.

(edit: updated since creation to reflect changes in PR)

References

(none)

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

[timhoffm]

IMHO the hyphened version is a readability improvement. OTOH it is a massive change. I'm +0.5 overall., but I leave it to @AA-Turner to do the tradeoff.

Concerning the PR: I suggest to split the actual change documentation and announcement from the mass-update. - At least by commits, but possibly even into separate PRs. First lets get the documentation and communication right - this is a small change but needs care to detail, because this change eventually affects a significant part of our users. Then, let's do our internal cleanup, which is a lot of churn but mostly a trivial replacement.

[stephenfin]

IMHO the hyphened version is a readability improvement. OTOH it is a massive change. I'm +0.5 overall., but I leave it to @AA-Turner to do the tradeoff.

I think the fact that we are not deprecating (in code) - and IMO should never deprecate - the older mechanism would limit the fallout of this. Newer docs can benefit from improved readability but older docs continue to work.

Concerning the PR: I suggest to split the actual change documentation and announcement from the mass-update. - At least by commits, but possibly even into separate PRs. First lets get the documentation and communication right - this is a small change but needs care to detail, because this change eventually affects a significant part of our users. Then, let's do our internal cleanup, which is a lot of churn but mostly a trivial replacement.

I've mostly done this already, but I can remove the outstanding changes to doc (a hangover from the previous revision of this PR, when we were only replacing deprecated with versiondeprecated) if helpful

[AA-Turner]

I've stripped this PR back to only introduce the new hypenated versions.

[AA-Turner]

Please don't force-push, it makes reviews harder on GH. Please could you also go back to the previous state of combined directives for both versions, rather than separate 'legacy alias' blocks? If we merge the hyphenated forms, I don't want to 'officially' deprecate the current forms for a year or two.

A

[stephenfin]

Please don't force-push, it makes reviews harder on GH.

Okay. I had to force push a final time to correct errant info in the commit message (I was still referencing the rework of the docs, which we're no longer doing here).

If no force pushes is a requirements, could I suggest adding this to the contributor guide (linked from CONTRIBUTING.rst)? Virtually all projects I've contributed to on GitHub and elsewhere ask for a clean git history so this would be an exception for me.

Please could you also go back to the previous state of combined directives for both versions, rather than separate 'legacy alias' blocks? If we merge the hyphenated forms, I don't want to 'officially' deprecate the current forms for a year or two.

Done, I think (assuming I understood the ask correctly). I've said this before though and I'll say it again: I really hope we don't ever remove the current forms. Reworking an existing project would be pure busywork for the same of 8 lines of code in Sphinx. If that's going to be a necessity I'd rather abandon this PR, tbh.

[AA-Turner]

If no force pushes is a requirements, could I suggest adding this to the contributor guide (linked from CONTRIBUTING.rst)?

Good idea. It's not a hard requirement -- force pushing is generally fine on a 'fresh' PR, but limitations in GitHub's review interface make it annoying for PRs that have been reviewed etc (e.g. the 'show recent changes' button no longer works, previous unresolved review comments are lost).

Virtually all projects I've contributed to on GitHub and elsewhere ask for a clean git history so this would be an exception for me.

We've used squash-merge in Sphinx since c. January 2023, which I find keeps the git history much cleaner. It's the same approach that we use in CPython and the other @python repositories with some sucecss. It means that the PR branch can be 'messy' but keeps the final commit as a single unit. But this is a somewhat recent change in workflow, so I agree good to write it down somewhere.

Done, I think (assuming I understood the ask correctly).

Sorry, I meant the state at

sphinx/doc/usage/restructuredtext/directives.rst

Lines 540 to 541 in 13796db

	.. rst:directive:: .. version-added:: version [brief explanation]
	.. versionadded:: version [brief explanation]

-- document both forms in the same place. I wrote a note here, but we could delete the "will be deprecated in a future version of Sphinx" line.

Whilst we're on the topic, what are your thoughts on :noindex vs :no-index:? I had planned to start deprecating the former in the next major version; the hyphenated option forms were first introduced in August 2023 (Sphinx 7.2). Given this train of thought though, we may want to hold off doing so.

A

[stephenfin]

If no force pushes is a requirements, could I suggest adding this to the contributor guide (linked from CONTRIBUTING.rst)?

Good idea. It's not a hard requirement -- force pushing is generally fine on a 'fresh' PR, but limitations in GitHub's review interface make it annoying for PRs that have been reviewed etc (e.g. the 'show recent changes' button no longer works, previous unresolved review comments are lost).

Virtually all projects I've contributed to on GitHub and elsewhere ask for a clean git history so this would be an exception for me.

We've used squash-merge in Sphinx since c. January 2023, which I find keeps the git history much cleaner. It's the same approach that we use in CPython and the other @python repositories with some sucecss. It means that the PR branch can be 'messy' but keeps the final commit as a single unit. But this is a somewhat recent change in workflow, so I agree good to write it down somewhere.

Understood. Let me put something together later on today.

(As an aside, it is mighty unfortunate that the GitHub PR/GitLab MR model is what caught on, as opposed to Gerrit's commit == change model. Alas)

Done, I think (assuming I understood the ask correctly).

Sorry, I meant the state at

sphinx/doc/usage/restructuredtext/directives.rst

Lines 540 to 541 in 13796db

	.. rst:directive:: .. version-added:: version [brief explanation]
	.. versionadded:: version [brief explanation]

-- document both forms in the same place. I wrote a note here, but we could delete the "will be deprecated in a future version of Sphinx" line.

Gotcha. I'll push that shortly.

Whilst we're on the topic, what are your thoughts on :noindex vs :no-index:? I had planned to start deprecating the former in the next major version; the hyphenated option forms were first introduced in August 2023 (Sphinx 7.2). Given this train of thought though, we may want to hold off doing so.

I would personally be inclined not to remove this. By all means, we could stop documenting it, but when you consider the many thousands (if not millions) of documents that would need changing and the resulting hours that would be wasted to allow us to delete a handful of lines here, it seems wrong.

Spoken as someone who still has scars from setuptool's decision to remove support for hyphen-separated options for the otherwise identical underscore-separated options 😅