From 06389410e97d4bea01900d53a5888bdd86dda50d Mon Sep 17 00:00:00 2001
From: Ezio Melotti <ezio.melotti@gmail.com>
Date: Tue, 10 May 2022 09:43:17 +0200
Subject: [PATCH] [3.8] gh-91888: add a `:gh:` role to the documentation
(GH-91889) (#91936)
* gh-91888: Add a :gh: role to the documentation (GH-91889).
* [3.8] gh-91888: add a `:gh:` role to the documentation (GH-91889)
* Add a new :gh:`...` role for GitHub issues.
* Fix a GitHub id to use the :gh: role.
* Add Misc/NEWS entry.
* Refactoring and rephrasing.
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>.
(cherry picked from commit f7641a2ffec243e5f600028a84debe9028a9ee44)
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
* Fix use of the default role in NEWS entry
---
Doc/tools/extensions/pyspecific.py | 26 ++++++++++++++++++-
...2-04-24-22-09-31.gh-issue-91888.kTjJLx.rst | 1 +
2 files changed, 26 insertions(+), 1 deletion(-)
create mode 100644 Misc/NEWS.d/next/Documentation/2022-04-24-22-09-31.gh-issue-91888.kTjJLx.rst
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index e3369cdc1eb..71ec09fd047 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -43,7 +43,8 @@
import suspicious
-ISSUE_URI = 'https://bugs.python.org/issue%s'
+ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s'
+GH_ISSUE_URI = 'https://github.com/python/cpython/issues/%s'
SOURCE_URI = 'https://github.com/python/cpython/tree/3.8/%s'
# monkey-patch reST parser to disable alphabetic and roman enumerated lists
@@ -58,11 +59,33 @@
def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
issue = utils.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 = utils.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], []
+
+
# Support for linking to Python source files easily
def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
@@ -575,6 +598,7 @@ def process_audit_events(app, doctree, fromdocname):
def setup(app):
app.add_role('issue', issue_role)
+ app.add_role('gh', gh_issue_role)
app.add_role('source', source_role)
app.add_directive('impl-detail', ImplementationDetail)
app.add_directive('availability', Availability)
diff --git a/Misc/NEWS.d/next/Documentation/2022-04-24-22-09-31.gh-issue-91888.kTjJLx.rst b/Misc/NEWS.d/next/Documentation/2022-04-24-22-09-31.gh-issue-91888.kTjJLx.rst
new file mode 100644
index 00000000000..4ebca42a7fe
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-04-24-22-09-31.gh-issue-91888.kTjJLx.rst
@@ -0,0 +1 @@
+Add a new ``gh`` role to the documentation to link to GitHub issues.
--
GitLab