diff options
| author | Ezio Melotti <ezio.melotti@gmail.com> | 2022-05-10 06:15:41 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-05-10 00:15:41 -0400 |
| commit | 73317e3c155446c6127b3d10a31ef421b73effe5 (patch) | |
| tree | 38cb312bb0558f4a0c9735c1ee83b0cc31f5e3af | |
| parent | 5da1197d51871cc7bb97a0de4d9bf99664579671 (diff) | |
| download | cpython-git-73317e3c155446c6127b3d10a31ef421b73effe5.tar.gz | |
[3.7] gh-91888: add a `:gh:` role to the documentation (GH-91889) (GH-91937)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>.
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
(cherry picked from commit f7641a2ffec243e5f600028a84debe9028a9ee44)
| -rw-r--r-- | Doc/tools/extensions/pyspecific.py | 24 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2022-04-24-22-09-31.gh-issue-91888.kTjJLx.rst | 1 |
2 files changed, 25 insertions, 0 deletions
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 37e2a696cf..e4f45414db 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -36,6 +36,7 @@ import suspicious 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.7/%s' # monkey-patch reST parser to disable alphabetic and roman enumerated lists @@ -81,11 +82,33 @@ LaTeXTranslator.depart_literal_block = new_depart_literal_block 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=[]): @@ -431,6 +454,7 @@ def parse_pdb_command(env, sig, signode): 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 0000000000..4ebca42a7f --- /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. |