FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

GH-121970: Extract ``issue_role`` into a new extension by AA-Turner · Pull Request #130615 · python/cpython · GitHub

/ cpython Public

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
+70 −35
Conversation 14 Commits 5 Checks 0 Files changed 3
Merged

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

Show file tree
Hide file tree
Changes from all commits
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 .py  (3) All 1 file type selected
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
1 change: 1 addition & 0 deletions Doc/conf.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
'glossary_search',
'grammar_snippet',
'implementation_detail',
'issue_role',
'lexers',
'misc_news',
'pydoc_topics',
Expand Down
69 changes: 69 additions & 0 deletions Doc/tools/extensions/issue_role.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
@@ -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:
Comment thread
AA-Turner marked this conversation as resolved.
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)

hugovk Feb 27, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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?

AA-Turner Feb 27, 2025

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

AA-Turner Feb 27, 2025

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

hugovk Feb 27, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

So should it match 12345 or bpo-12345?

hugovk Feb 27, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

(Unresolving so the question isn't hidden :)

AA-Turner Feb 27, 2025

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

return {
"version": "1.0",
"parallel_read_safe": True,
"parallel_write_safe": True,
}
35 changes: 0 additions & 35 deletions Doc/tools/extensions/pyspecific.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -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'

Expand All @@ -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):
Expand Down Expand Up @@ -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)
Expand Down
Back | FazBrowse Home | New Git URL