Docs: a start on an 'improve this page' feature #136246

nedbat · 2025-07-03T13:13:09Z

At the Docs WG meeting, we talked about smoothing the path for people to suggest improvements to the docs. This is a start. It uses more JavaScript than we are used to.

I haven't done anything to trim down the "Report a bug" page. Ideas welcome.

📚 Documentation preview 📚: https://cpython-previews--136246.org.readthedocs.build/

StanFromIreland

This looks great. I have some little thoughts.

Also, this should probably get an issue and blurb?

StanFromIreland · 2025-07-03T15:00:26Z

Doc/improvepage.rst

+
+- You can start a discussion about the page on the Python discussion forum.
+  This link will start a pre-populated topic:
+  `Question about "PAGETITLE" <https://discuss.python.org/new-topic?category=documentation&title=Question+about+%22PAGETITLE%22&body=About+the+page+at+PAGEURL%3A>`_.


I think we should use the path here, as otherwise it can be ambiguous, e.g. there are several Introduction in the docs.

Try the live version in the preview build. The body gets populated with the URL.

I see, the issue one however does not work for me, it sends me to the choose a template page. I also think good titles would be nice for triage/finding purposes.

It populates an issue for me, what are other people seeing?

I mean, when one opens an issue for a page like so where there are several pages with the same title, the issue title is then very ambiguous (e.g. in the above case, just „Introduction”).

The title will be simple but the body contains the URL, which is will be unambiguous. If the title is "Question about 'Introduction'" and then the body contains a link like https://cpython-previews--136246.org.readthedocs.build/en/136246/c-api/intro.html I think people will be able to discuss the correct page.

StanFromIreland · 2025-07-03T15:01:29Z

Doc/improvepage.rst

+  `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>`_.
+
+- You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_
+  and open a pull request, though you will need to have signed a contributor agreement before it can be merged.


Just a little note, I think mentioning the contribution agreement here may scare away people, as it does not explain much about it, and does not pop up when they edit the page.

Yes, I was torn about putting it here, we can drop it if needed.

I changed it to "open a pull request and begin the contribution process." to at least hint at the idea that there will be steps needed.

ryan-duve · 2025-07-04T01:29:15Z

I like the "This link will start a pre-populated topic:" link, but I wonder whether "less is more" applies here. In particular, I mean if the "Improve this page" link directly goes to the pre-populated Discourse form, would that more directly get users to where they can make a suggestion? If so, would it be better for "Improve this page" to link straight to Discourse?

nedbat · 2025-07-04T01:44:16Z

I like the "This link will start a pre-populated topic:" link, but I wonder whether "less is more" applies here. In particular, I mean if the "Improve this page" link directly goes to the pre-populated Discourse form, would that more directly get users to where they can make a suggestion? If so, would it be better for "Improve this page" to link straight to Discourse?

I'm not sure Discourse is the right place for everyone. Some people will have edits, some will have questions, some will want to discuss ideas for improvement. I appreciate the desire to make the path as well-greased as possible. If we do decide to link straight to Discourse, we'll need to change the link from "Improve this page", because Discourse is not the place to do that directly.

m-aciek · 2025-07-13T22:33:32Z

Doc/tools/templates/customsourcelink.html

      <li>
-        <a href="https://github.com/python/cpython/blob/main/Doc/{{ sourcename|replace('.rst.txt', '.rst') }}"
+        <a href="https://github.com/python/cpython/blob/main/Doc/{{ sourcename|replace('.rst.txt', '.rst?plain=1') }}"


Suggested change

<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"

Simplification suggestion; reference

hugovk · 2025-08-02T11:53:57Z

Doc/improvepage.rst

Let's rename to improve-page.rst (similar to other files)

Or e.g. suggest-improvement.rst?

improve-page.rst

hugovk · 2025-08-02T12:00:18Z

Doc/improvepage.rst

+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>`_.


If I do something like:

Go to the tutorial https://cpython-previews--136246.org.readthedocs.build/en/136246/tutorial/index.html

Click "Improve this page"

It says: 'You were reading “The Python Tutorial” at https://docs.python.org/3/tutorial/index.html. The source for that page is on GitHub.'

(This is fine)

Click "Improve this page" again while looking at "Improve a documentation page"

It says: 'You were reading “Improve a documentation page” at https://docs.python.org/3/tutorial/index.html. The source for that page is on GitHub.'

The page title has been updated, but the links are still for the tutorial. The other titles/links on the page are also mixed.

Should we:

Fix the links for the "Improve a documentation page"?

Fix the titles so it still refers to the tutorial?

Remove "Improve this page" from this page?

I've fixed this.

hugovk · 2025-08-02T12:02:42Z

Doc/tools/templates/customsourcelink.html

  <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('improvepage') }}?pageurl=https://docs.python.org/3/{{ pagename }}.html&pagesource={{ sourcename|replace('.rst.txt', '.rst') }}">{% trans %}Improve this page{% endtrans %}</a></li>


This hardcodes /3/.

What happens if I'm reading the 3.14 docs? Or the Spanish translation?

I've fixed this to use the actual full URL of the original page.

AA-Turner · 2025-08-02T14:35:50Z

Doc/improvepage.rst

+      <script>
+         document.addEventListener('DOMContentLoaded', () => {
+            const params = new URLSearchParams(window.location.search);
+            document.body.innerHTML = document.body.innerHTML
+               .replace(/PAGETITLE/g, params.get('pagetitle'))
+               .replace(/PAGEURL/g, params.get('pageurl'))
+               .replace(/PAGESOURCE/g, params.get('pagesource'));
+         });
+      </script>


Can we avoid inline JS? Ideally both here and the <script> in the template would be moved to .js files.

There are already two instances of inline script, and tbh, for small one-off chunks like this it might be more understandable to have them on the page where they are used. But in any case, would it be OK to land this feature first and then decide on centralization?

AA-Turner

I'd like to see if we can make this work as far as reasonably practical without JS -- we currently don't require users to have JS enabled to use the documentation.

On Hugo's point on translations, we could add another .. only:: block for non-English containing a brief description of changes to the translation vs source content.

A

StanFromIreland · 2025-08-02T15:28:09Z

On Hugo's point on translations, we could add another .. only:: block for non-English containing a brief description of changes to the translation vs source content.

For reference, the current practice for bugs.po, per PEP 545, is to stick it in somewhere at the end of an existing message.

I’m not a Sphinx expert but I don’t see how it would work, from my experience it can only exclude builders. If you could please share some Sphinx magic I’d love to open a PR for bugs.

nedbat · 2025-08-02T19:56:56Z

I'd like to see if we can make this work as far as reasonably practical without JS -- we currently don't require users to have JS enabled to use the documentation.

I'm happy to try another approach, but I'm not sure what we can do. The goal is for the Improve page to know what page the user was reading. Do you have another way?

- use the actual page URL - tighten the wording

nedbat · 2025-08-02T20:46:00Z

On Hugo's point on translations, we could add another .. only:: block for non-English containing a brief description of changes to the translation vs source content.

For reference, the current practice for bugs.po, per PEP 545, is to stick it in somewhere at the end of an existing message.

I’m not a Sphinx expert but I don’t see how it would work, from my experience it can only exclude builders. If you could please share some Sphinx magic I’d love to open a PR for bugs.

Maybe I don't understand the translation issue. What is the .. only:: block for?

Docs: a start on an 'improve this page' feature

673e347

nedbat force-pushed the nedbat/improve-docs-page branch from b8f50bc to 673e347 Compare July 3, 2025 14:57

StanFromIreland reviewed Jul 3, 2025

View reviewed changes

m-aciek reviewed Jul 13, 2025

View reviewed changes

nedbat mentioned this pull request Jul 27, 2025

Link to plaintext for "show source" links #137131

Merged

nedbat added 2 commits August 2, 2025 07:35

Merge branch 'main' into nedbat/improve-docs-page

2daceae

pr feedback: simplify the link, and don't scare people with the cla

3a768df

nedbat added skip issue skip news labels Aug 2, 2025

nedbat marked this pull request as ready for review August 2, 2025 11:37

nedbat requested review from AA-Turner and hugovk as code owners August 2, 2025 11:37

bedevere-app bot added the awaiting core review label Aug 2, 2025

hugovk reviewed Aug 2, 2025

View reviewed changes

AA-Turner reviewed Aug 2, 2025

View reviewed changes

nedbat added 2 commits August 2, 2025 16:20

pr feedback answered

32e27f6

- use the actual page URL - tighten the wording

fix the improve link on the improve page

7cc87b3

news item

e536574

nedbat removed the skip news label Aug 2, 2025

	<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"

		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>`_.

Uh oh!

Docs: a start on an 'improve this page' feature #136246

Are you sure you want to change the base?

Docs: a start on an 'improve this page' feature #136246

Uh oh!

Conversation

nedbat commented Jul 3, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryan-duve commented Jul 4, 2025

Uh oh!

nedbat commented Jul 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

StanFromIreland commented Aug 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nedbat commented Aug 2, 2025

Uh oh!

nedbat commented Aug 2, 2025

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

nedbat commented Jul 3, 2025 •

edited by github-actions bot

Loading

StanFromIreland commented Aug 2, 2025 •

edited

Loading