From de65166352b29ea7fef19104e856d039615b9194 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Thu, 27 Feb 2025 19:06:13 +0000 Subject: [PATCH] GH-121970: Extract ``issue_role`` into a new extension (GH-130615) (cherry picked from commit 043ab3af9ac81c6315395bef814fd12acb873b23) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/conf.py | 1 + Doc/tools/extensions/issue_role.py | 69 ++++++++++++++++++++++++++++++ Doc/tools/extensions/pyspecific.py | 35 --------------- 3 files changed, 70 insertions(+), 35 deletions(-) create mode 100644 Doc/tools/extensions/issue_role.py diff --git a/Doc/conf.py b/Doc/conf.py index d2892d550fbcd0..8e7ff47b260b2d 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -29,6 +29,7 @@ 'changes', 'glossary_search', '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 7625c2f314a92f..361b23fd9b0c0a 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/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)