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 <stephen@that.guru>

Author: stephenfin

doc/development/html_themes/index.rst

@@ -214,7 +214,7 @@ If your theme package contains two or more themes, please call
 .. versionadded:: 1.2
    'sphinx_themes' entry_points feature.
 
-.. deprecated:: 1.6
+.. versionchanged:: 1.6
    ``sphinx_themes`` entry_points has been deprecated.
 
 .. versionadded:: 1.6

doc/development/html_themes/templating.rst

@@ -188,24 +188,24 @@ is deprecated in favor of separate sidebar templates, which can be included via
 ``sidebartoc``
     The table of contents within the sidebar.
 
-    .. deprecated:: 1.0
+    .. version-deprecated:: 1.0
 
 ``sidebarrel``
     The relation links (previous, next document) within the sidebar.
 
-    .. deprecated:: 1.0
+    .. version-deprecated:: 1.0
 
 ``sidebarsourcelink``
     The "Show source" link within the sidebar (normally only shown if this is
     enabled by :confval:`html_show_sourcelink`).
 
-    .. deprecated:: 1.0
+    .. version-deprecated:: 1.0
 
 ``sidebarsearch``
     The search box within the sidebar.  Override this if you want to place some
     content at the bottom of the sidebar.
 
-    .. deprecated:: 1.0
+    .. version-deprecated:: 1.0
 
 
 Configuration Variables
@@ -237,7 +237,7 @@ Overriding works like this::
 
       {% set script_files = script_files + ["_static/myscript.js"] %}
 
-   .. deprecated:: 1.8.0
+   .. version-deprecated:: 1.8.0
 
       Please use ``.Sphinx.add_js_file()`` instead.
 

doc/extdev/markupapi.rst

@@ -203,7 +203,7 @@ and does not contain any structural elements
       with switch_source_input(self.state, self.result):
           parsed = nested_parse_to_nodes(self.state, self.result)
 
-   .. deprecated:: 1.7
+   .. version-deprecated:: 1.7
 
       Until Sphinx 1.6, ``sphinx.ext.autodoc.AutodocReporter`` was used for this
       purpose.  It is replaced by ``switch_source_input()``.

doc/latex.rst

@@ -288,7 +288,8 @@ Keys that you may want to override include:
 
    Default: ``''``
 
-   .. deprecated:: 1.5
+   .. version-deprecated:: 1.5
+
       Use ``'atendofbody'`` key instead.
 
 Keys that don't need to be overridden unless in special cases are:

doc/usage/configuration.rst

@@ -1157,7 +1157,7 @@ Options for source files
    The recommended encoding is ``'utf-8-sig'``.
 
    .. versionadded:: 0.5
-   .. deprecated:: 8.3
+   .. version-deprecated:: 8.3
       Support for source encodings other than UTF-8 is deprecated.
       Sphinx 10 will only support UTF-8 files.
 
@@ -1586,7 +1586,7 @@ and also make use of these options.
    .. versionadded:: 3.2
    .. versionchanged:: 4.0
       It defaults to :code-py:`'inline'`.
-   .. deprecated:: 4.0
+   .. version-deprecated:: 4.0
 
 .. confval:: html_context
    :type: :code-py:`dict[str, Any]`
@@ -1853,7 +1853,7 @@ and also make use of these options.
    .. versionadded:: 1.0
       The ability to use globbing keys and to specify multiple sidebars.
 
-   .. deprecated:: 1.7
+   .. version-deprecated:: 1.7
       A single string value for :confval:`!html_sidebars` will be removed.
 
    .. versionchanged:: 2.0
@@ -2103,7 +2103,8 @@ and also make use of these options.
             `Janome <https://pypi.org/project/Janome/>`_ is required.
 
 
-         .. deprecated:: 1.6
+         .. version-deprecated:: 1.6
+
             ``'mecab'``, ``'janome'`` and ``'default'`` is deprecated.
             To keep compatibility,
             ``'mecab'``, ``'janome'`` and ``'default'`` are also acceptable.

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

@@ -1117,7 +1117,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)