Skip to content

Commit 673e347

Browse files
committed
Docs: a start on an 'improve this page' feature
1 parent da79ac9 commit 673e347

File tree

2 files changed

+52
-1
lines changed

2 files changed

+52
-1
lines changed

Doc/improvepage.rst

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
:orphan:
2+
3+
.. _improve-a-page:
4+
5+
****************************
6+
Improve a documentation page
7+
****************************
8+
9+
.. only:: html and not epub
10+
11+
.. raw:: html
12+
13+
<script>
14+
document.addEventListener('DOMContentLoaded', () => {
15+
const params = new URLSearchParams(window.location.search);
16+
document.body.innerHTML = document.body.innerHTML
17+
.replace(/PAGETITLE/g, params.get('pagetitle'))
18+
.replace(/PAGEURL/g, params.get('pageurl'))
19+
.replace(/PAGESOURCE/g, params.get('pagesource'));
20+
});
21+
</script>
22+
23+
We are always interested to hear about ways to improve the documentation.
24+
25+
You were reading "PAGETITLE" at `<PAGEURL>`_. The source for that page is on
26+
`GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_.
27+
28+
You have a few options for asking questions or suggesting changes:
29+
30+
- You can start a discussion about the page on the Python discussion forum.
31+
This link will start a pre-populated topic:
32+
`Question about "PAGETITLE" <https://discuss.python.org/new-topic?category=documentation&title=Question+about+%22PAGETITLE%22&body=About+the+page+at+PAGEURL%3A>`_.
33+
34+
- You can open an issue on the Python GitHub issue tracker. This link will
35+
create a new issue pre-populated with some information for you:
36+
`Docs: problem with "PAGETITLE" <https://github.com/python/cpython/issues/new?title=Docs%3A+problem+with+%22PAGETITLE%22&labels=docs&body=The+page+at+PAGEURL+has+a+problem%3A>`_.
37+
38+
- You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_
39+
and open a pull request, though you will need to have signed a contributor agreement before it can be merged.

Doc/tools/templates/customsourcelink.html

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,22 @@
11
{%- if show_source and has_source and sourcename %}
2+
<script>
3+
document.addEventListener('DOMContentLoaded', () => {
4+
const title = document.querySelector('meta[property="og:title"]').content;
5+
const elements = document.querySelectorAll('.improvepage');
6+
elements.forEach(element => {
7+
const url = new URL(element.href);
8+
url.searchParams.set('pagetitle', title);
9+
element.href = url.toString();
10+
});
11+
});
12+
</script>
213
<div role="note" aria-label="source link">
314
<h3>{{ _('This page') }}</h3>
415
<ul class="this-page-menu">
516
<li><a href="{{ pathto('bugs') }}">{% trans %}Report a bug{% endtrans %}</a></li>
17+
<li><a class="improvepage" href="{{ pathto('improvepage') }}?pageurl=https://docs.python.org/3/{{ pagename }}.html&pagesource={{ sourcename|replace('.rst.txt', '.rst') }}">{% trans %}Improve this page{% endtrans %}</a></li>
618
<li>
7-
<a href="https://github.com/python/cpython/blob/main/Doc/{{ sourcename|replace('.rst.txt', '.rst') }}"
19+
<a href="https://github.com/python/cpython/blob/main/Doc/{{ sourcename|replace('.rst.txt', '.rst?plain=1') }}"
820
rel="nofollow">{{ _('Show source') }}
921
</a>
1022
</li>

0 commit comments

Comments
 (0)