Accessibility Enhancements #2949

jonathan343 · 2023-05-19T18:47:13Z

Overview

This PR provides two enhancements related to accessibility for the botocore/boto3 documentation websites.

Keyboard Navigation - Keyboard only users currently cant open/close the left or right sidebars since the related input label icons cannot be tabbed. This PR makes these labels (and other relevant ones) accessible through tabbing and adds new close icons to provide keyboard-only users a mechanism to open and close these sidebars.
Implicit Headings - A previous PR attempted to address some of these issues by keeping a list of STRONG_TO_H3_HEADINGS texts value we wanted to address. Since then, we've learned that we're responsible for converting more unpredictable values. This PR replaces the old method with a new one that uses the common pattern of <p><strong>Implicit Headings</strong><p> to detect and replace with <h3>Implicit Heading</h3>.

Solutions

Keyboard Navigation

Add labels that can be used for closing sidebars.
Make sure all open/close labels are only visible when necessary.

Note: There are two different labels/icons for opening the right sidebar (for the table of contents). One thats displayed
on medium sized screens and one thats displayed on smaller screens. This comes from Furo.

Enable tabbing for all labels with tabindex="0"
Activate input when a label is in focus and a user clicks "Enter".
The correct label should be put in focus after opening or closing a sidebar.

Example: When we open the right side bar, the close icon should be focused on. When we close the sidebar, the open
icon should be focused on. Same should happen for the left side bar. This feature is demonstrated in the section below.

Implicit Headings

To detect the pattern <p><strong>Implicit Headings</strong><p>

To do this we look for paragraph nodes who have only 1 child with the type docutil.nodes.strong. This child node must also only have 1 child node of the type docutil.nodes.Text. The text value of this node should not exist in our IGNORE_IMPLICIT_HEADINGS list.

When a node with the pattern above is detected, store the text value of the docutil.nodes.Text node and write this as an h3 tag instead.
raise nodes.SkipNode to skip visiting the current nodes children and its call of the depart method.

Demo

codecov-commenter · 2023-05-19T18:55:54Z

Codecov Report

Patch coverage has no change and project coverage change: -0.01 ⚠️

Comparison is base (97ba590) 93.29% compared to head (7e97fae) 93.28%.

❗ Your organization is not using the GitHub App Integration. As a result you may experience degraded service beginning May 15th. Please install the Github App Integration for your organization. Read more.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2949      +/-   ##
===========================================
- Coverage    93.29%   93.28%   -0.01%     
===========================================
  Files           64       64              
  Lines        13588    13589       +1     
===========================================
  Hits         12677    12677              
- Misses         911      912       +1

Impacted Files	Coverage Δ
botocore/docs/translator.py	`0.00% <0.00%> (ø)`

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

jonathan343 · 2023-05-19T19:12:08Z

docs/source/_templates/page.html

The GitHub diff is a bit messy and confusing. Here is screenshot provides a diff when compared to the original page.html from furo.

Nit: Seems strange that we have one modification surrounded by "[start/end] of AWS modifications of Furo template" but not the other modifications.

Updated the image with a new diff. I think i solved the issue you're talking about? It was extra whitespace and newlines.

botocore/docs/translator.py

jonemo · 2023-05-22T15:51:37Z

docs/source/_templates/sidebar/close-icon.html

+<div class="sidebar-div show-div-sm justify-content-right">
+    <label class="nav-close-icon" id="nav-menu-close" for="__navigation" tabindex="0">
+        <div class="visually-hidden">Toggle site navigation sidebar</div>
+        <i class="icon"><svg><use href="#svg-close"></use></svg></i>


What black magic is this? I've seen <use> for re-using SVG content within the same <svg> element, but this is re-using it from somewhere else?

I was mainly trying to stay as consistent as possible with what Furo does. They have an icons.html page where they define different symbols and later include this in page.html. There is no easy way to add symbols to this list so I added the new symbol directly here.

This seems like valid behavior according to svgwg.org

jonemo · 2023-05-22T16:05:46Z

docs/source/_templates/page.html

Nit: Seems strange that we have one modification surrounded by "[start/end] of AWS modifications of Furo template" but not the other modifications.

jonemo · 2023-05-22T16:23:05Z

docs/source/_templates/page.html

-        </div>
-    </a>
-    {%- endif %}
+{% block body -%}


What is the reason for the changes to template blocks? I think body is completely new and others have moved around.

So in furo's original page.html the footer block is nested in the body block. Previously, we only needed to modify the footer so utilizing jinja2's template inheritance we could just do:

{%- extends "!page.html" %} {% block footer %} # Custom HTML that overrides furo's footer block {%- endblock %}

This uses all the original body block content but replaces the footer block with what we defined. Ideally, as many things would be wrapped in its own block to make things more easily customizable without having to rewrite an entire template. In this case we need to modify elements in the body (outside of the footer), so we need to now do something like:

{%- extends "!page.html" %} {% block body %} # Custom HTML before footer {% block footer %} # Custom HTML that overrides furo's footer block {%- endblock %} # Custom HTML after footer {%- endblock %}

jonemo · 2023-05-22T16:24:42Z

docs/source/_templates/sidebar/close-icon.html

Where (and how) does this file get used? I only see the content of it duplicated in page.html, but no reference to this file.

This file gets referenced in conf.py. More information on customizing the left sidebar can be read on furo's doc site.

jonemo · 2023-05-22T16:26:05Z

docs/source/_static/css/custom.css

+    /* Hides the right sidebar on a medium screen by default. */
+    .toc-drawer {
+        display: none;
+    }


Is this PR actually changing when the toc drawer and sidebar drawer get shown?

No, but the way furo currently does this is by animating the left/right side bar outside the visible screen area by moving its position. The issue with this is that keyboard users can continue to tab/focus on elements they cant see. Applying the display: none; style prevents this behavior. The downside of this is that we loose the cool animation. Im looking into a way to achieve both.

jonemo · 2023-05-22T16:28:02Z

botocore/docs/translator.py

+        if (
+            len(node) == 1
+            and isinstance(node[0], nodes.strong)
+            and len(node[0]) == 1
+            and isinstance(node[0][0], nodes.Text)
+            and node[0][0].astext() not in self.IGNORE_IMPLICIT_HEADINGS
+        ):


Does this logic also need to handle situations like <p> <strong>Text</strong> </p> where there's a whitespace-only text node between the tags? Or does this logic get applied after the whitespace stripping from #2855 happens?

This logic happens after #2855 applies changes in the transition from upstream HTML --> RST. This translator extends the one from sphinx that is used in the transition from RST --> Boto Docs HTML.

nateprewitt

Cool, this all looks great. Thanks for the thorough deep dive on this @jonathan343 and it's exciting we may be able to port some of this back upstream.

My only question is how does that transition look if it is released in a future version of furo. Do we get that for free and can revert this or will we need to keep specific parts in the Translator/CSS/Page Template?

jonathan343 · 2023-05-24T20:19:59Z

My only question is how does that transition look if it is released in a future version of furo. Do we get that for free and can revert this or will we need to keep specific parts in the Translator/CSS/Page Template?

@nateprewitt If pradyunsg/furo#660 is ever merged and released in furo, we'll be able to revert the parts related to keyboard navigation (everything except changes to translator.py) since they'll be part of furo.

Improve keyboard navigation and remove extra implicit headings.

* release-1.29.142: Bumping version to 1.29.142 Update to latest partitions and endpoints Update to latest models Presigning content type bug (#2944) Accessibility Enhancements (#2949)

Improve keyboard navigation and remove extra implicit headings.

jonathan343 added 3 commits May 19, 2023 10:45

First checkpoint. Working open/close on enter.

e631b07

Keyboard navigation and implicit headings are working.

f93d48e

Make page.html formatting more similar to furo's version.

6415d7d

jonathan343 commented May 19, 2023

View reviewed changes

jonathan343 requested review from jonemo, nateprewitt and dlm6693 May 19, 2023 19:23

dlm6693 reviewed May 22, 2023

View reviewed changes

botocore/docs/translator.py Outdated Show resolved Hide resolved

botocore/docs/translator.py Outdated Show resolved Hide resolved

jonemo reviewed May 22, 2023

View reviewed changes

PR Feedback; Peserve sidebar animations.

7e97fae

nateprewitt approved these changes May 24, 2023

View reviewed changes

jonathan343 mentioned this pull request May 24, 2023

Keyboard Accessibility Improvements boto/boto3#3723

Merged

jonathan343 merged commit 00e1360 into boto:develop May 26, 2023
31 checks passed

dlm6693 pushed a commit to dlm6693/botocore that referenced this pull request May 26, 2023

Accessibility Enhancements (boto#2949)

07c7faa

Improve keyboard navigation and remove extra implicit headings.

dlm6693 pushed a commit to dlm6693/botocore that referenced this pull request May 30, 2023

Accessibility Enhancements (boto#2949)

e147c37

Improve keyboard navigation and remove extra implicit headings.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Accessibility Enhancements #2949

Accessibility Enhancements #2949

jonathan343 commented May 19, 2023 •

edited by dlm6693

codecov-commenter commented May 19, 2023 •

edited

jonathan343 May 19, 2023 •

edited

jonemo May 22, 2023

jonathan343 May 24, 2023

jonemo May 22, 2023

jonathan343 May 22, 2023

jonemo May 22, 2023

jonemo May 22, 2023

jonathan343 May 22, 2023

jonemo May 22, 2023

jonathan343 May 22, 2023 •

edited

jonemo May 22, 2023

jonathan343 May 22, 2023 •

edited

jonemo May 22, 2023

jonathan343 May 23, 2023 •

edited

nateprewitt left a comment

jonathan343 commented May 24, 2023

Accessibility Enhancements #2949

Accessibility Enhancements #2949

Conversation

jonathan343 commented May 19, 2023 • edited by dlm6693

Overview

Solutions

Demo

codecov-commenter commented May 19, 2023 • edited

Codecov Report

jonathan343 May 19, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan343 May 22, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan343 May 22, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan343 May 23, 2023 • edited

Choose a reason for hiding this comment

nateprewitt left a comment

Choose a reason for hiding this comment

jonathan343 commented May 24, 2023

jonathan343 commented May 19, 2023 •

edited by dlm6693

codecov-commenter commented May 19, 2023 •

edited

jonathan343 May 19, 2023 •

edited

jonathan343 May 22, 2023 •

edited

jonathan343 May 22, 2023 •

edited

jonathan343 May 23, 2023 •

edited