| 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 |
} |