GeezerVison

Documentation build overview

📚 CPython devguide | 🛠️ Build #32324346 | 📁 Comparing bd34ffc against latest (76bb6bb)

  🔍 Preview build  

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 now this gets tricky - DevGuide actually uses collapsible navigation tree for menu, but.. it doesn't conform to the guidelines itself. I tried several way to expand it on https://devguide.python.org/getting-started/ - right/left/space don't work, tab focus doesn't jump to down arrow. Enter just navigates to the section index page. So the menu tree is not ARIA compatible, and enabling keyboard navigation won't break it.

If somebody decides to make the devguide tree element ARIA compatible, the setting doesn't prevent more specific key handler to do the ARIA thing and prevent default popping to more generic document handler, where the shortcuts are defined.

https://github.com/sphinx-doc/sphinx/blob/cc7c6f435ad37bb12264f8118c8461b230e6830c/sphinx/themes/basic/static/doctools.js#L106

Thanks @abitrolly and @hugovk. I've opened an issue about accessibility #1792.

I am closing this PR as not planned.

@willingc please reopen. The accessibility was an argument that this PR would break it, but now that we've determined that there is nothing to break, I see no reason to keep keep these keyboard shortcuts disabled. They come from Spinx anyways.

We haven't determined there's nothing to break.

As I said at python/cpython#148751 (comment), some screen readers use left and right keys, and I think any interception of them could break accessibility. This isn't proven (I only tested VoiceOver on macOS, which isn't affected), but it's not proven the other way either.

@hugovk it works the other way around. It is screen reader that intercepts left and right keys first in "reading mode". So even if you try to intercept these keys in JavaScript, screen reader would be the first to catch them and do its thing,, and your JS code will do nothing.

@abitrolly While I can see your enthusiasm, I don't view this as a critical change right now without an accessibility audit. Thanks!

@willingc I doubt that accessibility audit is actionable. In any case, single-handedly cancelling this specific feature, and replacing it with generalization of accessibility audit is a bad move. There is no guarantee that the accessibility audit will happen, and that this feature will be there.

At least I would understand keeping it open until the audit is finished.

@abitrolly, Accessibility audits are actionable, and the Python ecosytem has done work to improve accessibility.

While you are welcome to your opinion, I'm unwilling to merge this right now. I'm not keen on keeping a one-line devguide PR open. If a core team member would like to reopen and mark DO-NOT-MERGE, I do not have any objection. I would prefer that an issue be opened to add next keyboard nav after validating accessibility impact to be more actionable.

@willingc created the issue to track the keyboard shortcuts python/docs-community#199

I also extended it to include vim style n/p keys now that there is a chance to get the proper a11y study. If the study shows that adding them improves UX without hurting a11y, then I will try to make sure Rust docs will get them too.