From ac39151a09fc9857e64d7b8f7eff926ec0ba6c0b Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 19 Jul 2024 08:33:51 +0100
Subject: [PATCH] GH-121970: Use ``SphinxDirective`` instead of ``Directive``
 (#121972)

---
 Doc/tools/extensions/pyspecific.py | 36 +++++++++++++-----------------
 1 file changed, 16 insertions(+), 20 deletions(-)

diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 8b592d4b4ad..77d5f123225 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -15,10 +15,9 @@ from os import getenv, path
 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 @@ std.token_re = re.compile(r'`((~?[\w-]*:)?\w+)`')
 # 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 @@ class AuditEvent(Directive):
         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 @@ class AuditEvent(Directive):
             )
             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 @@ class PyAbstractMethod(PyMethod):
 
 # 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 @@ class DeprecatedRemoved(Directive):
         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 @@ class DeprecatedRemoved(Directive):
                                                 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 @@ gh_issue_re = re.compile('(?:gh-issue-|gh-)([0-9]+)', re.I)
 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 @@ class MiscNews(Directive):
         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()