https://github.com/python/cpython/commit/043ab3af9ac81c6315395bef814fd12acb873b23
commit: 043ab3af9ac81c6315395bef814fd12acb873b23
branch: main
author: Adam Turner <9087854+aa-tur...@users.noreply.github.com>
committer: AA-Turner <9087854+aa-tur...@users.noreply.github.com>
date: 2025-02-27T19:06:13Z
summary:
GH-121970: Extract ``issue_role`` into a new extension (#130615)
Co-authored-by: Hugo van Kemenade <1324225+hug...@users.noreply.github.com>
files:
A Doc/tools/extensions/issue_role.py
M Doc/conf.py
M Doc/tools/extensions/pyspecific.py
diff --git a/Doc/conf.py b/Doc/conf.py
index 64d627bc41e6af..19538fe058ba2b 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -30,6 +30,7 @@
'glossary_search',
'grammar_snippet',
'implementation_detail',
+ 'issue_role',
'lexers',
'misc_news',
'pydoc_topics',
diff --git a/Doc/tools/extensions/issue_role.py
b/Doc/tools/extensions/issue_role.py
new file mode 100644
index 00000000000000..477b3a4b2d23b4
--- /dev/null
+++ b/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,
+ }
diff --git a/Doc/tools/extensions/pyspecific.py
b/Doc/tools/extensions/pyspecific.py
index 68247d40f682d1..f5451adb37b0b4 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/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/main/%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)
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
