fix screen reader accessibility of rustdoc item documentation

[ahicks92]

I opened this as one issue because the overarching problem is the problem, if you will. if I should have made a bunch, let me know.

Looks like the following applies to beta. Example page: https://doc.rust-lang.org/beta/std/collections/struct.BTreeMap.html

I'm a screen reader user (e.g. blind). Specifically NVDA. Whatever changes are coming down the pipeline with Rustdoc make the above-linked page difficult to navigate. It used to be the case that you could get used to the weird heading structure (specifically that Rustdoc headings are higher levels than example/error headings) then be mostly fine. But now:

• A lot of what used to be headings are exposed as buttons.
• All of those buttons like to start with [-], which screen readers are forced to listen to as "left bracket dash right bracket", e.g. "left bracket dash right bracket pub fn".
• There's a table of contents, but it only shows up if the page is maximized, and if there's a button to expand it I can't quickly find it.
• Said table of contents provides no way to quickly navigate it, e.g. "methods" being a heading, using lists, etc. I have to ctrl+f the categories.

I manage because I'm a screen reader power user who has previous familiarity with these pages, which meant that mostly getting around/through this was working out what actually changed rather than how to do it from scratch. It still hit my efficiency quite a bit. Most screen reader users aren't going to know to maximize their browser and ctrl+f "methods" and so on, or work out that actually sometimes you need next heading and sometimes you need next button.

Some concrete fixes:

• Put the h tags back (maybe we can do this with aria, if the buttons are important).
• move [-] to the end of the line, where it used to be. I think this can be faked with css if we need the visual representation to stay the same, but I'm a backend guy.
• Change the "headings" in the table of contents to be actual h tags, perhaps with nested links, or make the table of contents nested lists like mdbook.
• make sure that the table of contents is always visible, or that the button to expand/collapse it is more obvious if there is one.

I'm happy to discuss other fixes as well; my goal is to provide some sort of conversation starter.

[jyn514]

cc @jsha

[jyn514]

@ahicks92 when you say "coming down the pipeline" you specifically mean that these are changes in beta, that haven't made it to stable, right?

[jyn514]

Also, a broader question: your suggested changes seem fine to me, and I will try to make sure one or more of them land before the beta release, but how can we avoid regressions like this in the future? Do you know some software that can "rate" how accessible a page is, something like Google PageSpeed insights but for HTML layouts? Or are you maybe willing to donate a bit of your time every six weeks before a release? I can ask contributors to try their changes with a screen reader, but that seems like a burden to contributing to me; neither they nor I would really know what to look for.

[jyn514]

All of those buttons like to start with [-], which screen readers are forced to listen to as "left bracket dash right bracket", e.g. "left bracket dash right bracket pub fn".

Is there a way to tell screen readers not to read aloud certain buttons/divs? That seems like a better fix than just moving the buttons between the content.

[nagisa]

Looking at the accessiblity panel in the Firefox Developer tools it seems like at least as far as [-] is concerned, the problem is that the [-] has become the "summary" of some of the <details> elements. Since it is not a summary, the default roles are struggling to make the content sensible. I believe finding an appropriate aria role here and applying it to all of the <details> elements is going to be ideal.

---

Is there a way to tell screen readers not to read aloud certain buttons/divs? That seems like a better fix than just moving the buttons between the content.

Using aria-hidden="true" on some of the <summary> elements seems to hide the <summary> away from the screen reader tree, but I'm not sure how good of a practice that is. It won't work on the <summary>-ies of the methods, though as these populate [ - ] via CSS's ::before.

move [-] to the end of the line, where it used to be. I think this can be faked with css if we need the visual representation to stay the same, but I'm a backend guy.

Alas, the CSS pseudo elements are still included into the screen reader output and removing it is not trivial. It doesn't seem like WAI-ARIA has (ahem…) a way to specifically target CSS pseudo elements either.

We need to re-factor the DOM somewhat significantly here to get things work out I suspect.

---

when you say "coming down the pipeline" you specifically mean that these are changes in beta, that haven't made it to stable, right?

From looking at the accessibility trees and given the descriptions it seems like that's the correct interpretation.

---

A lot of what used to be headings are exposed as buttons.

I believe this refers to the fact that what previously was a

<h4 id="method.clear" class="method">
    <code>pub fn <a href="#method.clear" class="fnname">clear</a>(&amp;mut self)</code><a href="#method.clear" class="anchor"></a><a class="srclink" href="../../src/alloc/collections/btree/map.rs.html#512" title="goto source code">[src]</a><a href="javascript:void(0)" class="collapse-toggle">[<span class="inner">−</span>]</a>
</h4>

is now a

<summary><div id="method.clear" class="method has-srclink">
    <code>pub fn <a href="#method.clear" class="fnname">clear</a>(&amp;mut self)</code><a href="#method.clear" class="anchor"></a><a class="srclink" href="../../src/alloc/collections/btree/map.rs.html#512" title="goto source code">[src]</a>
</div></summary>

(i.e. the h4 was replaced with a div).

---

make sure that the table of contents is always visible, or that the button to expand/collapse it is more obvious if there is one.

I don't believe there is a way to hide the ToC (sidebar)…

EDIT: Ah, I see what you mean. It is hidden into a hamburger menu in mobile layout. And the button to display it is… not focus-able. There is attempt to make this hamburger act like a button:

<div class="sidebar-menu" role="button">☰</div>

but for some reason that doesn't work?

[nagisa]

Do you know some software that can "rate" how accessible a page is, something like Google PageSpeed insights but for HTML layouts?

I mention the Firefox's accessibility developer tools panel in the post above. It can be used to intuit what a screen reader would read without having to set up a full accessibility stack. It also has some lints in there, though they are pretty anemic still, as well as an ability to display tab order in a nice way.

[GuillaumeGomez]

• move [-] to the end of the line, where it used to be. I think this can be faked with css if we need the visual representation to stay the same, but I'm a backend guy.

Maybe I'm missing something but it has always been on the left of the items.

I don't believe there is a way to hide the ToC (sidebar)…

EDIT: Ah, I see what you mean. It is hidden into a hamburger menu in mobile layout. And the button to display it is… not focus-able. There is attempt to make this hamburger act like a button:

<div class="sidebar-menu" role="button">☰</div>

but for some reason that doesn't work?

This button is only relevant on mobile or on devices with small width. There is no way to hide the sidebar otherwise.

Also, overall our heading strategy was a complete mess, which was simplified/fixed by using the <details> and <summary> tags. Adding aria labels might make the situation better I think?

• make sure that the table of contents is always visible, or that the button to expand/collapse it is more obvious if there is one.

This button is only relevant for mobile devices where you can't have the sidebar alongside the content.

Anyway, we have a lot of progress to make on accessibility. I think integrated tools to ensure there is no big stepback in this regard would be a very nice improvement.

[nagisa]

Maybe I'm missing something but it has always been on the left of the items.

Previously at the DOM level they came after the pub fn ..., and were repositioned to appear on the “left” via CSS. From an excerpt I posted above (formatted further)

<h4 id="method.clear" class="method">
  <code>pub fn 
    <a href="#method.clear" class="fnname">clear</a>
    (&amp;mut self)</code>
    <a href="#method.clear" class="anchor"></a>
    <a class="srclink" href="../../src/alloc/collections/btree/map.rs.html#512" title="goto source code">[src]</a>
    <a href="javascript:void(0)" class="collapse-toggle">[<span class="inner">−</span>]</a>
    <!-- ^^^ HERE ^^^ -->
</h4>

---

This button is only relevant on mobile or on devices with small width. There is no way to hide the sidebar otherwise.

@ahicks92's complaint was specifically about the ToC only appearing when the browser window is maximized. Given that people using screenreaders don't usually need browsers rendering an entire screen worth of content, windows could get pretty small during their normal use.

[GuillaumeGomez]

Previously at the DOM level they came after the pub fn ..., and were repositioned to appear on the “left” via CSS. From an excerpt I posted above (formatted further)

Oh I see! I'm way to used at thinking about display and not about DOM... Thanks for the clarification!

@ahicks92's complaint was specifically about the ToC only appearing when the browser window is maximized. Given that people using screenreaders don't usually need browsers rendering an entire screen worth of content, windows could get pretty small during their normal use.

Is there a way to check if the page is rendered on a screenreader? If so, we could simply ignore the width in such a case and put the sidebar anyway.

[ahicks92]

Happy to see quick feedback. To answer questions in no particular order and hopefully without missing anything:

It does seem to be beta only. I've got an ongoing project in 1.53 which renders the old way, for lack of better phrasing.

For some reason my browser starts not fully maximized. When I maximize it I get the table of contents.

Screen readers like to read things in DOM order, so "end of the line" is indeed not really the best term for that. You can use CSS to make the visual order not match DOM and the screen readers still generally follow DOM order.

aria-hidden=true is generally fine, but I always caution people that there's no way for a screen reader user to know that it was applied without opening the web debugger, and if you put it on the wrong thing you will just make parts of the page vanish with no trace. That's not hard to avoid, but given that it's one of the more common "how do people misuse Aria in a way that I have to open the web debugger to fix it" bugs it's worth mentioning.

Fixing the table of contents probably "fixes" the order of elements on the line of the item itself, because the workflow here is/was using the h tags to find out what is available, and the point as far as I'm concerned is fixing the workflow. For myself, I'm satisfied as long as there's a quick way to skim method names.

To the best of my knowledge, there isn't any good software for detecting this sort of accessibility issue, because this sort of accessibility issue is kind of subjective. You'd have to try very hard to make rustdoc so bad it's literally unusable at all, and the sorts of things like this aren't nearly so simple as "this font is white on white". I've never heard anyone managing to automate a screen reader navigation efficiency test. But I'm a non-accessibility backend dev so maybe there is. I believe there's more objective linters (e.g. this is an unlabeled link) but you would have to ask someone else for them, and frankly every browser/screen reader pair has different and uniquely special bugs. There's at least 16 that can matter before you even consider version numbers.

You can find a lot of good accessibility-related info at WebAIM or in the WCAG and the various guides and things people have written about WCAG. It's not all entirely on point though, and it's also kind of interesting in that by the time someone is a programmer they're also a power user and efficiency starts mattering and shifts the trade-off from nice, long labels to a preference for terseness (or does for me--but that may be subjective).

I probably don't have the bandwidth to do a lengthy audit every 6 weeks, but I'm happy to at least try to serve as a smoke test if someone pings me about it.

[ahicks92]

Going to also drop this here: https://docs.rs/prost/0.8.0/prost/trait.Message.html

Which has "left bracket minus right bracket go to source code" before everything. Looking at rust beta stdlib, that's not there for at least PartialOrd, so maybe it's a docs.rs theming issue, or docs.rs is on a newer nightly than beta.