Enable keyboard navigation for Python docs

[abitrolly]

You can test how it works before this change by opening JavaScript console with F12 and setting

DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS=true

then make sure the focus is in the main are and press Left on the keyboard.

The option is documented here https://www.sphinx-doc.org/en/master/usage/theming.html#:~:text=navigation%5Fwith%5Fkeys

---

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

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[hugovk]

Copying my comment from python/devguide#1784 (comment):

---

Nice little shortcut, but I'm concerned this will interfere with keyboard handling for people using assistive tech such as screen readers.

https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/ includes:

So, screen reader users will commonly expect that pressing the right arrow key will expand a collapsed node.

https://webaim.org/techniques/keyboard/ has examples where ←/→ keys are needed.

[abitrolly]

Nice little shortcut, but I'm concerned this will interfere with keyboard handling for people using assistive tech such as screen readers.

https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/ includes:

So, screen reader users will commonly expect that pressing the right arrow key will expand a collapsed node.

https://webaim.org/techniques/keyboard/ has examples where ←/→ keys are needed.

@hugovk keyboard shortcuts are disabled for these HTML elements - "TEXTAREA", "INPUT", "SELECT", "BUTTON" (https://github.com/sphinx-doc/sphinx/blob/cc7c6f435ad37bb12264f8118c8461b230e6830c/sphinx/themes/basic/static/doctools.js#L6-L11)

Is that enough for Python docs? The ARIA guidelines are too generic - they say "Consider, for example, a screen reader user operating a tree.", but as far as I can tell there are no expandable trees in Python docs.

[hugovk]

My understanding is that screen readers use left and right to navigate character-by-character:

For example the left/right cursor keys are intercepted and used to move focus to the previous/next character in the content, and the up/down keys move focus to the previous/next line instead of scrolling the page.

https://tink.uk/understanding-screen-reader-interaction-modes/

While using screen reader such as NVDA, when left or right key is pressed, the screen reader reads the current or next element letter by letter.

https://stackoverflow.com/questions/70304270/while-using-screen-reader-such-as-nvda-how-to-press-left-or-right-key

Or for navigating table cells:

https://dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts

So any other interception of arrow keys would be a problem.

[abitrolly]

For example the left/right cursor keys are intercepted and used to move focus to the previous/next character in the content, and the up/down keys move focus to the previous/next line instead of scrolling the page.

If the screen reader indeed intercepts the left/right keys to provide its own functions, then the problem doesn't exist.

We need a screen reader user to test that https://cpython-previews--148751.org.readthedocs.build/en/148751/tutorial/index.html page doesn't trigger navigation to next when right arrow key is pressed while screen reader is active. The link goes to the tutorial page, because front page doesn't have next links).

[github-actions]

This PR is stale because it has been open for 90 days with no activity.

[abitrolly]

@hugovk can you help @willingc make accessibility audit? I see the resolution is not going anywhere.

Maybe just quick fix and fix cycle can do better.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33783193 | 📁 Comparing f74809f against main (9e23652)

🔍 Preview build

293 files changed · + 9 added · ± 283 modified · - 1 deleted

+Added

• c-api/sentinel.html
• c-api/slots.html
• deprecations/pending-removal-in-3.21.html
• howto/abi3t-migration.html
• library/asyncio-threading.html
• library/asyncio-tools.html
• library/tkinter.fontchooser.html
• library/tkinter.systray.html
• whatsnew/3.16.html

±Modified

• bugs.html
• glossary.html
• index.html
• license.html
• py-modindex.html
• c-api/buffer.html
• c-api/bytes.html
• c-api/code.html
• c-api/complex.html
• c-api/concrete.html
• and 273 more...

-Deleted

• library/asyncio-policy.html

[StanFromIreland]

I'm closing this for now, as I don't see support from any core devs for this change. Additionally, I'm not sure I see user demand either. You opened similar PRs across many repositories in a short period, so out of curiosity, do you actually use this feature?

[hugovk]

@hugovk can you help @willingc make accessibility audit? I see the resolution is not going anywhere.

Maybe just quick fix and fix cycle can do better.

Joining the dots, I replied at python/docs-community#199 (comment).