[3.12] GH-121970: Use SphinxDirective instead of Directive (GH-121972) (#122009)

GH-121970: Use ``SphinxDirective`` instead of ``Directive`` (GH-121972)
(cherry picked from commit ac39151)

Co-authored-by: Adam Turner <[email protected]>

Author: miss-islington

Doc/tools/extensions/pyspecific.py

@@ -15,10 +15,9 @@
 from time import asctime
 from pprint import pformat
 
-from docutils import nodes, utils
+from docutils import nodes
 from docutils.io import StringOutput
-from docutils.parsers.rst import Directive
-from docutils.utils import new_document
+from docutils.utils import new_document, unescape
 from sphinx import addnodes
 from sphinx.builders import Builder
 from sphinx.domains.python import PyFunction, PyMethod
@@ -52,7 +51,7 @@
 # Support for marking up and linking to bugs.python.org issues
 
 def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
-    issue = utils.unescape(text)
+    issue = unescape(text)
     # sanity check: there are no bpo issues within these two values
     if 47261 < int(issue) < 400000:
         msg = inliner.reporter.error(f'The BPO ID {text!r} seems too high -- '
@@ -67,7 +66,7 @@ def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
 # Support for marking up and linking to GitHub issues
 
 def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
-    issue = utils.unescape(text)
+    issue = unescape(text)
     # sanity check: all GitHub issues have ID >= 32426
     # even though some of them are also valid BPO IDs
     if int(issue) < 32426:
@@ -82,7 +81,7 @@ def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
 
 # Support for marking up implementation details
 
-class ImplementationDetail(Directive):
+class ImplementationDetail(SphinxDirective):
 
     has_content = True
     final_argument_whitespace = True
@@ -214,7 +213,7 @@ def audit_events_merge(app, env, docnames, other):
             env.all_audit_events[name] = value
 
 
-class AuditEvent(Directive):
+class AuditEvent(SphinxDirective):
 
     has_content = True
     required_arguments = 1
@@ -244,15 +243,14 @@ def run(self):
         text = label.format(name="``{}``".format(name),
                             args=", ".join("``{}``".format(a) for a in args if a))
 
-        env = self.state.document.settings.env
-        if not hasattr(env, 'all_audit_events'):
-            env.all_audit_events = {}
+        if not hasattr(self.env, 'all_audit_events'):
+            self.env.all_audit_events = {}
 
         new_info = {
             'source': [],
             'args': args
         }
-        info = env.all_audit_events.setdefault(name, new_info)
+        info = self.env.all_audit_events.setdefault(name, new_info)
         if info is not new_info:
             if not self._do_args_match(info['args'], new_info['args']):
                 self.logger.warning(
@@ -272,7 +270,7 @@ def run(self):
             )
             ids.append(target)
 
-        info['source'].append((env.docname, target))
+        info['source'].append((self.env.docname, target))
 
         pnode = nodes.paragraph(text, classes=["audit-hook"], ids=ids)
         pnode.line = self.lineno
@@ -310,7 +308,7 @@ class audit_event_list(nodes.General, nodes.Element):
     pass
 
 
-class AuditEventListDirective(Directive):
+class AuditEventListDirective(SphinxDirective):
 
     def run(self):
         return [audit_event_list('')]
@@ -395,7 +393,7 @@ def run(self):
 
 # Support for documenting version of removal in deprecations
 
-class DeprecatedRemoved(Directive):
+class DeprecatedRemoved(SphinxDirective):
     has_content = True
     required_arguments = 2
     optional_arguments = 1
@@ -411,8 +409,7 @@ def run(self):
         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('.'))
+        current_version = tuple(int(e) for e in self.config.version.split('.'))
         removed_version = tuple(int(e) for e in self.arguments[1].split('.'))
         if current_version < removed_version:
             label = self._deprecated_label
@@ -444,8 +441,7 @@ def run(self):
                                                 classes=['versionmodified']),
                                    translatable=False)
             node.append(para)
-        env = self.state.document.settings.env
-        env.get_domain('changeset').note_changeset(node)
+        self.env.get_domain('changeset').note_changeset(node)
         return [node] + messages
 
 
@@ -456,7 +452,7 @@ def run(self):
 whatsnew_re = re.compile(r"(?im)^what's new in (.*?)\??$")
 
 
-class MiscNews(Directive):
+class MiscNews(SphinxDirective):
     has_content = False
     required_arguments = 1
     optional_arguments = 0
@@ -471,7 +467,7 @@ def run(self):
         if not source_dir:
             source_dir = path.dirname(path.abspath(source))
         fpath = path.join(source_dir, fname)
-        self.state.document.settings.record_dependencies.add(fpath)
+        self.env.note_dependency(path.abspath(fpath))
         try:
             with io.open(fpath, encoding='utf-8') as fp:
                 content = fp.read()