Hyphenate versioning admonitions

Use e.g. 'version-changed' over 'versionchanged'. 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 the 'deprecated' 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). Changes to the other admonitions will be kept to a
separate commit to keep this one reviewable.

Signed-off-by: Stephen Finucane <[email protected]>

Author: stephenfin

doc/usage/restructuredtext/directives.rst

@@ -537,7 +537,7 @@ Describing changes between versions
            pair: changes; in version
            pair: removed; in version
 
-.. rst:directive:: .. versionadded:: version [brief explanation]
+.. rst:directive:: .. version-added:: version [brief explanation]
 
    This directive documents the version of the project
    which added the described feature.
@@ -553,57 +553,84 @@ Describing changes between versions
 
    Example::
 
-      .. versionadded:: 2.5
+      .. version-added:: 2.5
          The *spam* parameter.
 
-   .. versionadded:: 2.5
+   .. version-added:: 2.5
       The *spam* parameter.
 
-.. rst:directive:: .. versionchanged:: version [brief explanation]
+.. rst:directive:: .. version-changed:: version [brief explanation]
 
-   Similar to :rst:dir:`versionadded`, but describes when and what changed in
+   Similar to :rst:dir:`version-added`, but describes when and what changed in
    the named feature in some way (new parameters, changed side effects, etc.).
 
    Example::
 
-      .. versionchanged:: 2.8
+      .. version-changed:: 2.8
          The *spam* parameter is now of type *boson*.
 
-   .. versionchanged:: 2.8
+   .. version-changed:: 2.8
       The *spam* parameter is now of type *boson*.
 
-.. rst:directive:: .. deprecated:: version [brief explanation]
+.. rst:directive:: .. version-deprecated:: version [brief explanation]
 
-   Similar to :rst:dir:`versionadded`, but describes when the feature was
+   Similar to :rst:dir:`version-added`, but describes when the feature was
    deprecated.
    A *brief* explanation can also be given,
    for example to tell the reader what to use instead.
 
+   .. version-added:: 8.3
+
    Example::
 
-      .. deprecated:: 3.1
+      .. version-deprecated:: 3.1
          Use :py:func:`spam` instead.
 
-   .. deprecated:: 3.1
+   .. version-deprecated:: 3.1
       Use :py:func:`!spam` instead.
 
-.. rst:directive:: .. versionremoved:: version [brief explanation]
+.. rst:directive:: .. version-removed:: version [brief explanation]
 
-   Similar to :rst:dir:`versionadded`, but describes when the feature was removed.
+   Similar to :rst:dir:`version-added`, but describes when the feature was removed.
    An explanation may be provided to tell the reader what to use instead,
    or why the feature was removed.
 
-   .. versionadded:: 7.3
+   .. version-added:: 7.3
 
    Example::
 
-      .. versionremoved:: 4.0
+      .. version-removed:: 4.0
          The :py:func:`spam` function is more flexible, and should be used instead.
 
-   .. versionremoved:: 4.0
+   .. version-removed:: 4.0
       The :py:func:`!spam` function is more flexible, and should be used instead.
 
 
+.. rst:directive:: .. versionadded:: version [brief explanation]
+
+   A legacy alias for :rst:dir:`version-added`.
+
+   .. version-deprecated:: 8.3
+
+.. rst:directive:: .. versionchanged:: version [brief explanation]
+
+   A legacy alias for :rst:dir:`version-changed`.
+
+   .. version-deprecated:: 8.3
+
+.. rst:directive:: .. deprecated:: version [brief explanation]
+
+   A legacy alias for :rst:dir:`version-deprecated`.
+
+   .. version-deprecated:: 8.3
+
+.. rst:directive:: .. versionremoved:: version [brief explanation]
+
+   A legacy alias for :rst:dir:`version-removed`.
+
+   .. version-deprecated:: 8.3
+
+
 Presentational
 ^^^^^^^^^^^^^^
 

sphinx/addnodes.py

@@ -402,8 +402,8 @@ class desc_sig_literal_char(desc_sig_element, _sig_element=True):
 class versionmodified(nodes.Admonition, nodes.TextElement):
     """Node for version change entries.
 
-    Currently used for "versionadded", "versionchanged", "deprecated"
-    and "versionremoved" directives.
+    Currently used for "version-added", "version-changed", "version-deprecated"
+    and "version-removed" directives, along with their aliases.
     """
 
 

sphinx/application.py

@@ -1118,7 +1118,7 @@ def setup(app):
 
         .. versionchanged:: 0.6
            Docutils 0.5-style directive classes are now supported.
-        .. deprecated:: 1.8
+        .. versionchanged:: 1.8
            Docutils 0.4-style (function based) directives support is deprecated.
         .. versionchanged:: 1.8
            Add *override* keyword.

sphinx/builders/changes.py

@@ -23,7 +23,7 @@
 
 
 class ChangesBuilder(Builder):
-    """Write a summary with all versionadded/changed/deprecated/removed directives."""
+    """Write a summary with all version-related directives."""
 
     name = 'changes'
     epilog = __('The overview file is in %(outdir)s.')
@@ -43,6 +43,11 @@ def get_outdated_docs(self) -> str:
         return str(self.outdir)
 
     typemap = {
+        'version-added': 'added',
+        'version-changed': 'changed',
+        'version-deprecated': 'deprecated',
+        'version-removed': 'removed',
+        # deprecated aliases
         'versionadded': 'added',
         'versionchanged': 'changed',
         'deprecated': 'deprecated',
@@ -112,6 +117,11 @@ def write_documents(self, _docnames: Set[str]) -> None:
             f.write(self.templates.render('changes/versionchanges.html', ctx))
 
         hltext = [
+            f'.. version-added:: {version}',
+            f'.. version-changed:: {version}',
+            f'.. version-deprecated:: {version}',
+            f'.. version-removed:: {version}',
+            # deprecated alises
             f'.. versionadded:: {version}',
             f'.. versionchanged:: {version}',
             f'.. deprecated:: {version}',

sphinx/domains/changeset.py

@@ -21,6 +21,12 @@
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
+name_aliases = {
+    'version-added': 'versionadded',
+    'version-changed': 'versionchanged',
+    'version-deprecated': 'deprecated',
+    'version-removed': 'versionremoved',
+}
 
 versionlabels = {
     'versionadded': _('Added in version %s'),
@@ -56,12 +62,13 @@ class VersionChange(SphinxDirective):
     option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
+        name = name_aliases.get(self.name, self.name)
         node = addnodes.versionmodified()
         node.document = self.state.document
         self.set_source_info(node)
-        node['type'] = self.name
+        node['type'] = name
         node['version'] = self.arguments[0]
-        text = versionlabels[self.name] % self.arguments[0]
+        text = versionlabels[name] % self.arguments[0]
         if len(self.arguments) == 2:
             inodes, messages = self.parse_inline(
                 self.arguments[1], lineno=self.lineno + 1
@@ -73,7 +80,7 @@ def run(self) -> list[Node]:
             messages = []
         if self.content:
             node += self.parse_content_to_nodes()
-        classes = ['versionmodified', versionlabel_classes[self.name]]
+        classes = ['versionmodified', versionlabel_classes[name]]
         if len(node) > 0 and isinstance(node[0], nodes.paragraph):
             # the contents start with a paragraph
             if node[0].rawsource:
@@ -168,6 +175,10 @@ def get_changesets_for(self, version: str) -> list[ChangeSet]:
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_domain(ChangeSetDomain)
+    app.add_directive('version-added', VersionChange)
+    app.add_directive('version-changed', VersionChange)
+    app.add_directive('version-deprecated', VersionChange)
+    app.add_directive('version-removed', VersionChange)
     app.add_directive('deprecated', VersionChange)
     app.add_directive('versionadded', VersionChange)
     app.add_directive('versionchanged', VersionChange)

tests/roots/test-changes/base.rst

@@ -1,23 +1,38 @@
 Version markup
 --------------
 
-.. versionadded:: 0.6
+.. version-added:: 0.6
    Some funny **stuff**.
 
-.. versionchanged:: 0.6
+.. version-changed:: 0.6
    Even more funny stuff.
 
-.. deprecated:: 0.6
+.. version-deprecated:: 0.6
    Boring stuff.
 
-.. versionremoved:: 0.6
+.. version-removed:: 0.6
    Goodbye boring stuff.
 
-.. versionadded:: 1.2
+.. version-added:: 1.2
+
+   First paragraph of version-added.
+
+.. version-changed:: 1.2
+   First paragraph of version-changed.
+
+   Second paragraph of version-changed.
 
-   First paragraph of versionadded.
+.. version-deprecated:: 1.3
+   First paragraph of version-deprecated.
 
-.. versionchanged:: 1.2
-   First paragraph of versionchanged.
+.. version-added:: 0.6
+   Deprecated alias
 
-   Second paragraph of versionchanged.
+.. version-changed:: 0.6
+   Deprecated alias
+
+.. versionremoved:: 0.6
+   Deprecated alias
+
+.. deprecated:: 0.6
+   Deprecated alias

tests/roots/test-changes/c-api.rst

@@ -8,7 +8,7 @@ Memory
 
    Allocate *n* bytes of memory.
 
-   .. versionchanged:: 0.6
+   .. version-changed:: 0.6
 
       Can now be replaced with a different allocator.
 
@@ -17,7 +17,7 @@ System
 
 Access to the system allocator.
 
-.. versionadded:: 0.6
+.. version-added:: 0.6
 
 .. c:function:: void* Test_SysMalloc(size_t n)
 

tests/roots/test-changes/library/utils.rst

@@ -16,10 +16,10 @@ Classes
 
    Class for handling paths.
 
-   .. versionadded:: 0.5
+   .. version-added:: 0.5
 
-      Innovative new way to handle paths.
+       Innovative new way to handle paths.
 
-    .. deprecated:: 0.6
+   .. version-deprecated:: 0.6
 
        So, that was a bad idea it turns out.

tests/roots/test-intl/versionchange.txt

@@ -3,16 +3,16 @@
 i18n with versionchange
 ============================
 
-.. deprecated:: 1.0
-   This is the *first* paragraph of deprecated.
+.. version-deprecated:: 1.0
+   This is the *first* paragraph of version-deprecated.
 
-   This is the *second* paragraph of deprecated.
+   This is the *second* paragraph of version-deprecated.
 
-.. versionadded:: 1.0
-   This is the *first* paragraph of versionadded.
+.. version-added:: 1.0
+   This is the *first* paragraph of version-added.
 
-.. versionchanged:: 1.0
+.. version-changed:: 1.0
 
-   This is the *first* paragraph of versionchanged.
+   This is the *first* paragraph of version-changed.
 
-.. versionremoved:: 1.0 This is the *first* paragraph of versionremoved.
+.. version-removed:: 1.0 This is the *first* paragraph of version-removed.

tests/roots/test-intl/xx/LC_MESSAGES/versionchange.po

@@ -19,12 +19,24 @@ msgstr ""
 msgid "i18n with versionchange"
 msgstr "I18N WITH VERSIONCHANGE"
 
+msgid "This is the *first* paragraph of version-deprecated."
+msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-DEPRECATED."
+
+msgid "This is the *second* paragraph of version-deprecated."
+msgstr "THIS IS THE *SECOND* PARAGRAPH OF VERSION-DEPRECATED."
+
+msgid "This is the *first* paragraph of version-added."
+msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-ADDED."
+
+msgid "This is the *first* paragraph of version-changed."
+msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-CHANGED."
+
+msgid "This is the *first* paragraph of version-removed."
+msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSION-REMOVED."
+
 msgid "This is the *first* paragraph of deprecated."
 msgstr "THIS IS THE *FIRST* PARAGRAPH OF DEPRECATED."
 
-msgid "This is the *second* paragraph of deprecated."
-msgstr "THIS IS THE *SECOND* PARAGRAPH OF DEPRECATED."
-
 msgid "This is the *first* paragraph of versionadded."
 msgstr "THIS IS THE *FIRST* PARAGRAPH OF VERSIONADDED."