From f7641a2ffec243e5f600028a84debe9028a9ee44 Mon Sep 17 00:00:00 2001
From: Ezio Melotti <ezio.melotti@gmail.com>
Date: Mon, 25 Apr 2022 12:05:54 +0200
Subject: [PATCH] gh-91888: add a `:gh:` role to the documentation (#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>
---
 Doc/tools/extensions/pyspecific.py            | 24 +++++++++++++++++++
 Doc/whatsnew/3.11.rst                         |  2 +-
 ...2-04-24-22-09-31.gh-issue-91888.kTjJLx.rst |  1 +
 3 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 80533a97b11..12b98f49f69 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -44,6 +44,7 @@
 
 
 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/main/%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=[]):
@@ -615,6 +638,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/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index ba85b7896b2..ebaa1e993e2 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -463,7 +463,7 @@ inspect
   line number, column and end column). The affected functions are:
   :func:`inspect.getframeinfo`, :func:`inspect.getouterframes`, :func:`inspect.getinnerframes`,
   :func:`inspect.stack` and :func:`inspect.trace`. (Contributed by Pablo Galindo in
-  :issue:`88116`)
+  :gh:`88116`)
 
 locale
 ------
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..9194be9dbf9
--- /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.