Repository navigation
Feature: Add right/left n/p keyboard navigation to all Python docs #199
Description
Activity
Arrow keys
OK, so digging further into this, and following discussion in python/cpython#148751 (and other PRs and issues), I think mapping the arrow keys to previous and next pages (
navigation_with_keys=True) is not a good fit for keyboard users.Reasons:
-
It gets in the way of horizontal scroll. For example, you're tabbing down the argparse page and want to scroll the wide code block to see the code hidden on the right. The right arrow takes you to another page. This also leads on to:
-
Accidental press loses your reading position. For example, you're pressing the down arrow to scroll down a page. You accidentally press the right arrow and it takes you to the next page, at the top. Oops, press left to go back. But you're at the top of the first page. Some of our pages are very long, this is not a good experience.
-
The PyData Sphinx Theme has had accessibility audits. They discovered
navigation_with_keyswas turned on, and turned it off for these reasons, and noted it's probably a violation of WCAG 2.1.4 - Character Key Shortcuts (Level A): -
See also some discussion in Enable navigation_with_keys by default in themes with responsive design sphinx-doc/sphinx#12227 where it was rejected in Sphinx (I forgot I'd been pinged in that thread) based on the experience/advice of PyData Sphinx Theme.
n/p keys
These might be a better choice, I've not checked in detail. However, the CPython docs define
accesskey="P"andaccesskey="N", which means on macOS/Chrome you can already use Ctrl+Opt+P or N to change page! (Likely some other modifiers on other OS/browser.)
[I've transferred this issue from the devguide repo to docs-community because it's about all docs]
Reacted by Stan Ulbrych, Petr Viktorin and Pradyun Gedam-
- It gets in the way of horizontal scroll. For example, you're tabbing down the argparse page and want to scroll the wide code block to see the code hidden on the right. The right arrow takes you to another page.
@hugovk previewing python/cpython#148751 https://cpython-previews--148751.org.readthedocs.build/en/148751/library/argparse.html#suggest-on-error
Your are right. The element with the code is rendered as
<pre>:
But Sphinx keyboard navigation code only ignores these:
const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ "TEXTAREA", "INPUT", "SELECT", "BUTTON", ]);
It is possible to add PRE and CODE to ignore list, or disable the processing if
element.scrollWidth > element.clientWidth(meaning the element doesn't fit the visible area and needs to be scrolled).-
This also leads on to:
-
Accidental press loses your reading position. For example, you're pressing the down arrow to scroll down a page. You accidentally press the right arrow and it takes you to the next page, at the top. Oops, press left to go back. But you're at the top of the first page. Some of our pages are very long, this is not a good experience.
Rust docs has no solution to losing position on long pages https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html for forward/backward navigation. I guess the solution is to push current scroll state to browser history before navigating forward.
It already starts to look like the keyboard_navigation should have its own repo with issues. 😁
noted it's probably a violation of WCAG 2.1.4 - Character Key Shortcuts (Level A):
How to check/test it is not?
the CPython docs define
accesskey="P"andaccesskey="N", which means on macOS/Chrome you can already use Ctrl+Opt+P or N to change page! (Likely some other modifiers on other OS/browser.)The browser+OS shenanigans leads to degraded UX while jumping between stations. Better stick to uniform solutions when possible.
I asked this on the CPython PR, but you may have missed it: I'm not sure I see user demand here. You opened similar PRs across many repositories in a short period, so out of curiosity, do you actually use this feature?
Reacted by Carol WillingI asked this on the CPython PR, but you may have missed it: I'm not sure I see user demand here. You opened similar PRs across many repositories in a short period, so out of curiosity, do you actually use this feature?
Yes. For pretty much everything written in https://rust-lang.github.io/mdBook/index.html I use keyboard to jump to next page. That's mostly forward pacing tutorials and books structured to give complete readable info on one page, but when I need to just go to the following page, the habit is already there.
The PyData Sphinx theme has had extensive accessibility research work done for it to provide more compliance for working in academic and government institutions. I recommend that we follow their lead when it comes to accessibility. This work was partially funded by a CZI EOSS grant.
Reacted by Hugo van Kemenade and Stan Ulbrych
Describe the enhancement or feature you would like
Right now the accessibility audit python/devguide#1792 is blocking keyboard navigation python/devguide#1784 not only for devguide, but across Python ecosysem https://github.com/orgs/sphinx-doc/discussions/14406 sphinx-doc/sphinx#14408 readthedocs/sphinx_rtd_theme#1686 pradyunsg/furo#932
Clearly, other projects may not have the resources to access the risk of hurting sensitive auditory, so all maintainers just don't take it - and while Sphinx comes with keyboard shortcuts, no project across Pyto ecosystem enables it.
Now that there is a chance to do accessibility study, please make sure that both arrow keys and
vim`style n/p keys are evaluated for usage, with official "documentation accessibility" chapter, that could be easily referenced for other projects to follow.Thanks for your time, folks.
Describe alternatives you have considered
No response
Additional context
No response