https://github.com/python/cpython/commit/a81554f587a8d373588308ef476f12a17e4ed43d commit: a81554f587a8d373588308ef476f12a17e4ed43d branch: 3.14 author: Ned Batchelder <[email protected]> committer: nedbat <[email protected]> date: 2026-02-18T05:27:09-05:00 summary:
[3.14] Docs: an "improve this page" feature (GH-144939) (#144943) --------- (cherry picked from commit 7a7521bcfad4a8346d460476de2e3fa11e412477) Co-authored-by: Stan Ulbrych <[email protected]> files: A Doc/improve-page-nojs.rst A Doc/improve-page.rst A Misc/NEWS.d/next/Documentation/2025-08-02-18-59-01.gh-issue-136246.RIK7nE.rst M Doc/tools/templates/customsourcelink.html diff --git a/Doc/improve-page-nojs.rst b/Doc/improve-page-nojs.rst new file mode 100644 index 00000000000000..91b3a88b95d38b --- /dev/null +++ b/Doc/improve-page-nojs.rst @@ -0,0 +1,29 @@ +:orphan: + +**************************** +Improve a documentation page +**************************** + +.. This is the no-javascript version of this page. The one most people + will see (with JavaScript enabled) is improve-page.rst. If you edit + this page, please also edit that one, and vice versa. + +.. only:: html and not epub + +We are always interested to hear ideas about improvements to the documentation. + +.. only:: translation + + If the bug or suggested improvement concerns the translation of this + documentation, open an issue or edit the page in + `translation's repository <TRANSLATION_REPO_>`_ instead. + +You have a few ways to ask questions or suggest changes: + +- You can start a discussion about the page on the Python discussion forum. + This link will start a topic in the Documentation category: + `New Documentation topic <https://discuss.python.org/new-topic?category=documentation>`_. + +- You can open an issue on the Python GitHub issue tracker. This link will + create a new issue with the "docs" label: + `New docs issue <https://github.com/python/cpython/issues/new?template=documentation.yml>`_. diff --git a/Doc/improve-page.rst b/Doc/improve-page.rst new file mode 100644 index 00000000000000..dc89fcb22fbb59 --- /dev/null +++ b/Doc/improve-page.rst @@ -0,0 +1,65 @@ +:orphan: + +**************************** +Improve a documentation page +**************************** + +.. This is the JavaScript-enabled version of this page. Another version + (for those with JavaScript disabled) is improve-page-nojs.rst. If you + edit this page, please also edit that one, and vice versa. + +.. only:: html and not epub + + .. raw:: html + + <script> + function applyReplacements(text, params) { + return text + .replace(/PAGETITLE/g, params.get('pagetitle')) + .replace(/PAGEURL/g, params.get('pageurl')) + .replace(/PAGESOURCE/g, params.get('pagesource')); + } + + document.addEventListener('DOMContentLoaded', () => { + const params = new URLSearchParams(window.location.search); + const walker = document.createTreeWalker( + document.body, + NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, + null + ); + + while (walker.nextNode()) { + const node = walker.currentNode; + + if (node.nodeType === Node.TEXT_NODE) { + node.textContent = applyReplacements(node.textContent, params) + } else if (node.nodeName === 'A' && node.href) { + node.setAttribute('href', applyReplacements(node.getAttribute('href'), params)); + } + } + }); + </script> + +We are always interested to hear ideas about improvements to the documentation. + +You were reading "PAGETITLE" at `<PAGEURL>`_. The source for that page is on +`GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_. + +.. only:: translation + + If the bug or suggested improvement concerns the translation of this + documentation, open an issue or edit the page in + `translation's repository <TRANSLATION_REPO_>`_ instead. + +You have a few ways to ask questions or suggest changes: + +- You can start a discussion about the page on the Python discussion forum. + This link will start a pre-populated topic: + `Question about page "PAGETITLE" <https://discuss.python.org/new-topic?category=documentation&title=Question+about+page+%22PAGETITLE%22&body=About+the+page+at+PAGEURL%3A>`_. + +- You can open an issue on the Python GitHub issue tracker. This link will + create a new pre-populated issue: + `Docs: problem with page "PAGETITLE" <https://github.com/python/cpython/issues/new?template=documentation.yml&title=Docs%3A+problem+with+page+%22PAGETITLE%22&description=The+page+at+PAGEURL+has+a+problem%3A>`_. + +- You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_ + to open a pull request and begin the contribution process. diff --git a/Doc/tools/templates/customsourcelink.html b/Doc/tools/templates/customsourcelink.html index 0d83ac9f78adb9..8feeed2fee3650 100644 --- a/Doc/tools/templates/customsourcelink.html +++ b/Doc/tools/templates/customsourcelink.html @@ -1,10 +1,25 @@ {%- if show_source and has_source and sourcename %} + <script> + document.addEventListener('DOMContentLoaded', () => { + const title = document.querySelector('meta[property="og:title"]').content; + const elements = document.querySelectorAll('.improvepage'); + const pageurl = window.location.href.split('?')[0]; + elements.forEach(element => { + const url = new URL(element.href.split('?')[0].replace("-nojs", "")); + url.searchParams.set('pagetitle', title); + url.searchParams.set('pageurl', pageurl); + url.searchParams.set('pagesource', "{{ pagename }}.rst"); + element.href = url.toString(); + }); + }); + </script> <div role="note" aria-label="source link"> <h3>{{ _('This page') }}</h3> <ul class="this-page-menu"> <li><a href="{{ pathto('bugs') }}">{% trans %}Report a bug{% endtrans %}</a></li> + <li><a class="improvepage" href="{{ pathto('improve-page-nojs') }}">{% trans %}Improve this page{% endtrans %}</a></li> <li> - <a href="https://github.com/python/cpython/blob/main/Doc/{{ sourcename|replace('.rst.txt', '.rst') }}?plain=1" + <a href="https://github.com/python/cpython/blob/main/Doc/{{ pagename }}.rst?plain=1" rel="nofollow">{{ _('Show source') }} </a> </li> diff --git a/Misc/NEWS.d/next/Documentation/2025-08-02-18-59-01.gh-issue-136246.RIK7nE.rst b/Misc/NEWS.d/next/Documentation/2025-08-02-18-59-01.gh-issue-136246.RIK7nE.rst new file mode 100644 index 00000000000000..5f83785df13209 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-08-02-18-59-01.gh-issue-136246.RIK7nE.rst @@ -0,0 +1,3 @@ +A new "Improve this page" link is available in the left-hand sidebar of the +docs, offering links to create GitHub issues, discussion forum posts, or +pull requests. _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
