From 06bd386899925a1eeb5dec0eac58ffd699828666 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Thu, 18 Jul 2024 15:35:37 +0100
Subject: [PATCH] GH-121970: Make ``DeprecatedRemoved`` a subclass of
 ``VersionChange``

Also allow the ``.. versionremoved::`` directive to be used whilst we still support older versions of Sphinx.
---
 Doc/tools/extensions/pyspecific.py | 72 +++++++++++-------------------
 1 file changed, 26 insertions(+), 46 deletions(-)

diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 8b592d4b4adcea..3ee0df9df1e322 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -15,12 +15,14 @@
 from time import asctime
 from pprint import pformat
 
+import sphinx
 from docutils import nodes, utils
 from docutils.io import StringOutput
 from docutils.parsers.rst import Directive
 from docutils.utils import new_document
 from sphinx import addnodes
 from sphinx.builders import Builder
+from sphinx.domains.changeset import VersionChange, versionlabels, versionlabel_classes
 from sphinx.domains.python import PyFunction, PyMethod
 from sphinx.errors import NoUri
 from sphinx.locale import _ as sphinx_gettext
@@ -395,58 +397,34 @@ def run(self):
 
 # Support for documenting version of removal in deprecations
 
-class DeprecatedRemoved(Directive):
-    has_content = True
+class DeprecatedRemoved(VersionChange):
     required_arguments = 2
-    optional_arguments = 1
-    final_argument_whitespace = True
-    option_spec = {}
 
-    _deprecated_label = sphinx_gettext('Deprecated since version {deprecated}, will be removed in version {removed}')
-    _removed_label = sphinx_gettext('Deprecated since version {deprecated}, removed in version {removed}')
+    _deprecated_label = sphinx_gettext('Deprecated since version %s, will be removed in version %s')
+    _removed_label = sphinx_gettext('Deprecated since version %s, removed in version %s')
 
     def run(self):
-        node = addnodes.versionmodified()
-        node.document = self.state.document
-        node['type'] = 'deprecated-removed'
-        version = (self.arguments[0], self.arguments[1])
-        node['version'] = version
-        env = self.state.document.settings.env
-        current_version = tuple(int(e) for e in env.config.version.split('.'))
-        removed_version = tuple(int(e) for e in self.arguments[1].split('.'))
+        # Replace the first two arguments (deprecated version and removed version)
+        # with a single tuple of both versions.
+        version_deprecated = self.arguments[0]
+        version_removed = self.arguments.pop(1)
+        self.arguments[0] = version_deprecated, version_removed
+
+        # Set the label based on if we have reached the removal version
+        current_version = tuple(map(int, self.config.version.split('.')))
+        removed_version = tuple(map(int,  version_removed.split('.')))
         if current_version < removed_version:
-            label = self._deprecated_label
-        else:
-            label = self._removed_label
-
-        text = label.format(deprecated=self.arguments[0], removed=self.arguments[1])
-        if len(self.arguments) == 3:
-            inodes, messages = self.state.inline_text(self.arguments[2],
-                                                      self.lineno+1)
-            para = nodes.paragraph(self.arguments[2], '', *inodes, translatable=False)
-            node.append(para)
+            versionlabels[self.name] = self._deprecated_label
+            versionlabel_classes[self.name] = 'deprecated'
         else:
-            messages = []
-        if self.content:
-            self.state.nested_parse(self.content, self.content_offset, node)
-        if len(node):
-            if isinstance(node[0], nodes.paragraph) and node[0].rawsource:
-                content = nodes.inline(node[0].rawsource, translatable=True)
-                content.source = node[0].source
-                content.line = node[0].line
-                content += node[0].children
-                node[0].replace_self(nodes.paragraph('', '', content, translatable=False))
-            node[0].insert(0, nodes.inline('', '%s: ' % text,
-                                           classes=['versionmodified']))
-        else:
-            para = nodes.paragraph('', '',
-                                   nodes.inline('', '%s.' % text,
-                                                classes=['versionmodified']),
-                                   translatable=False)
-            node.append(para)
-        env = self.state.document.settings.env
-        env.get_domain('changeset').note_changeset(node)
-        return [node] + messages
+            versionlabels[self.name] = self._removed_label
+            versionlabel_classes[self.name] = 'removed'
+        try:
+            return super().run()
+        finally:
+            # reset versionlabels and versionlabel_classes
+            versionlabels[self.name] = ''
+            versionlabel_classes[self.name] = ''
 
 
 # Support for including Misc/NEWS
@@ -699,6 +677,8 @@ def setup(app):
     app.add_directive('audit-event', AuditEvent)
     app.add_directive('audit-event-table', AuditEventListDirective)
     app.add_directive('deprecated-removed', DeprecatedRemoved)
+    if sphinx.version_info[:2] < (7, 3):
+        app.add_directive('versionremoved', VersionChange)
     app.add_builder(PydocTopicsBuilder)
     app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
     app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command)