🌐 AI搜索 & 代理 主页
Skip to content

GH-121970: Extract issue_role into a new extension #130615

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AA-Turner merged 5 commits into from
Feb 27, 2025
Merged

GH-121970: Extract issue_role into a new extension #130615

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dd80b62
Extract ``issue_role`` into a new extension
AA-Turner Feb 26, 2025
28087ba
Convert to SphinxRole
AA-Turner Feb 26, 2025
0282cf3
Remove {GH_}ISSUE_URI from `pyspecific`
AA-Turner Feb 26, 2025
6fa8680
Hugo's review
AA-Turner Feb 27, 2025
3b46c04
Revert TC=False
AA-Turner Feb 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Convert to SphinxRole
  • Loading branch information
@AA-Turner
AA-Turner committed Feb 26, 2025
commit 28087ba6c27dbd5507972fa96ce710e24c1e7f80
109 changes: 48 additions & 61 deletions Doc/tools/extensions/issue_role.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,79 +1,66 @@
"""Support for marking up and linking to the issues in the tracker."""
"""Support for referencing issues in the tracker."""

from __future__ import annotations

from collections.abc import Sequence
from typing import TYPE_CHECKING

from docutils import nodes
from docutils.parsers.rst.states import Inliner
from docutils.utils import unescape

from sphinx.util.docutils import SphinxRole

if TYPE_CHECKING:
from typing import Any

from docutils.nodes import Node
from docutils.nodes import Element
from sphinx.application import Sphinx
from sphinx.util.typing import ExtensionMetadata


ISSUE_URI = "https://bugs.python.org/issue?@action=redirect&bpo=%s"
GH_ISSUE_URI = "https://github.com/python/cpython/issues/%s"


def issue_role(
typ: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: dict[str, Any] = {},
content: Sequence[str] = [],
) -> tuple[list[Node], list[nodes.system_message]]:
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], []


def gh_issue_role(
typ: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: dict[str, Any] = {},
content: Sequence[str] = [],
) -> tuple[list[Node], list[nodes.system_message]]:
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 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)
Copy link
Member

@hugovk hugovk Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here we're passing something like 12345 and bpo-12345 as the first two arguments.

Before we were passing something like bpo-12345 and bpo-12345 for both.

I see the second one is used in the refnode:

<reference refuri="https://bugs.python.org/issue?@action=redirect&bpo=13936">bpo-13936</reference>

How is the first one used?

Copy link
Member Author

@AA-Turner AA-Turner Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the docutils rawsource, it should reflect what was actually written in the document.

Sphinx uses this for translation, I don't think these nodes are translatable but I'll double check.

A

Copy link
Member Author

@AA-Turner AA-Turner Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See e.g. https://github.com/python/python-docs-fr/blob/3.13/whatsnew/3.13.po#L394-L399, the whole role is included in the translation string.

Copy link
Member

@hugovk hugovk Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So should it match 12345 or bpo-12345?

Copy link
Member

@hugovk hugovk Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Unresolving so the question isn't hidden :)

Copy link
Member Author

@AA-Turner AA-Turner Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text of what is actually written in the document, so "14159".

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", issue_role)
app.add_role("gh", gh_issue_role)
app.add_role("issue", BPOIssue())
app.add_role("gh", GitHubIssue())

return {
"version": "1.0",
Expand Down
Loading