Debian Codegraph @

Doc/tools/extensions/issue_role.py

raw
1 """Support for referencing issues in the tracker."""
2
3 from __future__ import annotations
4
5 from typing import TYPE_CHECKING
6
7 from docutils import nodes
8 from sphinx.util.docutils import SphinxRole
9
10 if TYPE_CHECKING:
11 from docutils.nodes import Element
12 from sphinx.application import Sphinx
13 from sphinx.util.typing import ExtensionMetadata
14
15
16 class BPOIssue(SphinxRole):
17 ISSUE_URI = "https://bugs.python.org/issue?@action=redirect&bpo={0}"
18
19 def run(self) -> tuple[list[Element], list[nodes.system_message]]:
20 issue = self.text
21
22 # sanity check: there are no bpo issues within these two values
23 if 47_261 < int(issue) < 400_000:
24 msg = self.inliner.reporter.error(
25 f"The BPO ID {issue!r} seems too high. "
26 "Use :gh:`...` for GitHub IDs.",
27 line=self.lineno,
28 )
29 prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
30 return [prb], [msg]
31
32 issue_url = self.ISSUE_URI.format(issue)
33 refnode = nodes.reference(issue, f"bpo-{issue}", refuri=issue_url)
34 self.set_source_info(refnode)
35 return [refnode], []
36
37
38 class GitHubIssue(SphinxRole):
39 ISSUE_URI = "https://github.com/python/cpython/issues/{0}"
40
41 def run(self) -> tuple[list[Element], list[nodes.system_message]]:
42 issue = self.text
43
44 # sanity check: all GitHub issues have ID >= 32426
45 # even though some of them are also valid BPO IDs
46 if int(issue) < 32_426:
47 msg = self.inliner.reporter.error(
48 f"The GitHub ID {issue!r} seems too low. "
49 "Use :issue:`...` for BPO IDs.",
50 line=self.lineno,
51 )
52 prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
53 return [prb], [msg]
54
55 issue_url = self.ISSUE_URI.format(issue)
56 refnode = nodes.reference(issue, f"gh-{issue}", refuri=issue_url)
57 self.set_source_info(refnode)
58 return [refnode], []
59
60
61 def setup(app: Sphinx) -> ExtensionMetadata:
62 app.add_role("issue", BPOIssue())
63 app.add_role("gh", GitHubIssue())
64
65 return {
66 "version": "1.0",
67 "parallel_read_safe": True,
68 "parallel_write_safe": True,
69 }