Plan to improve accessibility documentation (and testing)

[bollwyvl]

Hi folks!

• builds on Improve accessibility of the theme #61

It looks like the lighthouse check (#206) hasn't been taken out 🎉, but I haven't been monitoring closely to find out if it has actually caught any regressions! If so, it might be interesting to write it up in the development section.

More broadly: I've recently been digging into some tools for helping devs think about accessibility concerns while developing, and not waiting until a site is live and someone comes with a genuine issue. It seems for something that's upstream a few levels from where most audiences will actually be trying to read stuff, we can have a big impact here.

Here's a relatively-low-effort incremental plan to getting to a place where it can be iteratively improved.

docs

• add an accessibility page to the docs suite
  • specifically thinking about accessibility from the sensory/cognitive perspective
    • but could perhaps be expanded to localization (Translations for page elements #257) and privacy (e.g. GDPR), as these constitute things that might exclude audiences (practically/legally)
• outline what this theme (and documentation site) does, with practical examples, to address these matters:
  • content
  • the HTML/JS/CSS/Python itself
  • continuous integration

testing

• in CI and (optionally) locally, run an open source accessibility check against the example site
  • since nodejs is sitting around in CI, the go-to appears to be pa11y-ci
    • it does pull in puppeteer (sigh)
    • this works particularly well with a sitemap.xml, and can account for mangling the "production" URL, so...
• to get the sitemap, use sphinx-sitemap to generate during the build
  • happily, this would help SEO for the actual published docs site :)
  • sadly, this doesn't mean what WCAG means when they say "sitemap", which is more like an index page, and probably a separate matter :(
• add some config to ignore the initial warnings
  • little preview: hacking this toolchain on a local site based on this theme yields... over 1000!
• maybe add a nice HTML report to CI

implementation

• start fixing the warnings!
  • a huge swathe of these would be covered by a number of independent, "good first issue" PRs which would a) fix the thing and b) re-enable a rule
    • ENH: add icon_links option for custom navbar icons (with docs and pypi example) #293 icon links have no text Make social buttons extendable #270 (comment)
    • default color contrast
    • default pygments themes
    • sidebar search form (no submit button, placeholder-only text)

I'm happy to get the ball rolling, but would ❤️ any other feedback and thoughts!

[bollwyvl]

Ha: RTD already generates a sitemap for the production site:

https://pydata-sphinx-theme.readthedocs.io/sitemap.xml

I have no idea how it would interact with sphinx-sitemap, so that would likely need to be disabled when running there in their environment.

[bollwyvl]

PR up: #294

[jpmckinney]

Issue description is that this "builds on #61", but is this not the same as #61? What is the difference?

[trallard]

Folks looking at this issue - this seems no longer applicable, i.e. this was later implemented in other PRs.
I will be opening other issues for accessibility work so could we close this one to avoid confusion over what has/will be/is currently being done?

[drammock]

Superceded by #1168