GH-121970: Extract issue_role into a new extension (GH-130615)

(cherry picked from commit 043ab3a)

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

Author: 2 people

Doc/conf.py

@@ -29,6 +29,7 @@
     'changes',
     'glossary_search',
     'implementation_detail',
+    'issue_role',
     'lexers',
     'misc_news',
     'pydoc_topics',

Doc/tools/extensions/issue_role.py

@@ -0,0 +1,69 @@
+"""Support for referencing issues in the tracker."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxRole
+
+if TYPE_CHECKING:
+    from docutils.nodes import Element
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+
+class BPOIssue(SphinxRole):
+    ISSUE_URI = "https://bugs.python.org/issue?@action=redirect&bpo={0}"
+
+    def run(self) -> tuple[list[Element], list[nodes.system_message]]:
+        issue = self.text
+
+        # sanity check: there are no bpo issues within these two values
+        if 47_261 < int(issue) < 400_000:
+            msg = self.inliner.reporter.error(
+                f"The BPO ID {issue!r} seems too high. "
+                "Use :gh:`...` for GitHub IDs.",
+                line=self.lineno,
+            )
+            prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
+            return [prb], [msg]
+
+        issue_url = self.ISSUE_URI.format(issue)
+        refnode = nodes.reference(issue, f"bpo-{issue}", refuri=issue_url)
+        self.set_source_info(refnode)
+        return [refnode], []
+
+
+class GitHubIssue(SphinxRole):
+    ISSUE_URI = "https://github.com/python/cpython/issues/{0}"
+
+    def run(self) -> tuple[list[Element], list[nodes.system_message]]:
+        issue = self.text
+
+        # sanity check: all GitHub issues have ID >= 32426
+        # even though some of them are also valid BPO IDs
+        if int(issue) < 32_426:
+            msg = self.inliner.reporter.error(
+                f"The GitHub ID {issue!r} seems too low. "
+                "Use :issue:`...` for BPO IDs.",
+                line=self.lineno,
+            )
+            prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
+            return [prb], [msg]
+
+        issue_url = self.ISSUE_URI.format(issue)
+        refnode = nodes.reference(issue, f"gh-{issue}", refuri=issue_url)
+        self.set_source_info(refnode)
+        return [refnode], []
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_role("issue", BPOIssue())
+    app.add_role("gh", GitHubIssue())
+
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

Doc/tools/extensions/pyspecific.py

@@ -21,9 +21,6 @@
 from sphinx.locale import _ as sphinx_gettext
 from sphinx.util.docutils import SphinxDirective
 
-
-ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s'
-GH_ISSUE_URI = 'https://github.com/python/cpython/issues/%s'
 # Used in conf.py and updated here by python/release-tools/run_release.py
 SOURCE_URI = 'https://github.com/python/cpython/tree/3.12/%s'
 
@@ -34,36 +31,6 @@
     Body.enum.converters['lowerroman'] = \
     Body.enum.converters['upperroman'] = lambda x: None
 
-# Support for marking up and linking to bugs.python.org issues
-
-def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
-    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 -- '
-                                     'use :gh:`...` for GitHub IDs', line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-    text = 'bpo-' + issue
-    refnode = nodes.reference(text, text, refuri=ISSUE_URI % issue)
-    return [refnode], []
-
-
-# Support for marking up and linking to GitHub issues
-
-def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
-    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:
-        msg = inliner.reporter.error(f'The GitHub ID {text!r} seems too low -- '
-                                     'use :issue:`...` for BPO IDs', line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-    text = 'gh-' + issue
-    refnode = nodes.reference(text, text, refuri=GH_ISSUE_URI % issue)
-    return [refnode], []
-
 
 class PyAwaitableMixin(object):
     def handle_signature(self, sig, signode):
@@ -160,8 +127,6 @@ def patch_pairindextypes(app, _env) -> None:
 
 
 def setup(app):
-    app.add_role('issue', issue_role)
-    app.add_role('gh', gh_issue_role)
     app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
     app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command)
     app.add_object_type('monitoring-event', 'monitoring-event', '%s (monitoring event)', parse_monitoring_event)