Accessibility

Creating and publishing content that does not exclude audiences with limited abilities of various kinds is challenging, but also important, to achieve and then maintain.

While there is no one-size-fits-all solution to maintaining accessible content, this theme and documentation site use some techniques to avoid common content shortcomings.

Note

Issues and pull requests to identify or fix accessibility issues on this theme or site are heartily welcomed!

In Configuration

Some minor configuration options in a site’s conf.py can impact the accessibility of content generated by this theme, and Sphinx in general.

Natural Language

If not using a more robust internationalization approach , specifying at least the baseline natural language will help assistive technology identify if the content is in a language the reader understands.

Hint

Specifying a language will propagate to the top-level html tag.

language = "en"

Site Map

Site maps, usually served from a file called sitemap.xml are a broadly-employed approach to telling programs like search engines and assistive technologies where different content appears on a website.

If using a service like ReadTheDocs, these files will be created for you automatically, but for some of the other approaches below, it’s handy to generate a sitemap.xml locally or in CI with a tool like sphinx-sitemap.

Hint

For a simple site (no extra languages or versions), ensure sphinx-sitemap is installed in your documentation environment, and modify your conf.py:

extensions += ["sphinx_sitemap"]

html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/")
sitemap_locales = [None]
sitemap_url_scheme = "{link}"

In Your Source

Note

Stay tuned for more ideas here as we learn more working on this site!

In the Browser

A number of in-browser tools exist for interactively debugging the accessibility of a single page at a time, and can be useful during the content development cycle.

Built-in tools

Most major browsers, including Firefox and Chrome include significant accessibility tooling in their development experience. Exploring these, and the modes they offer, can help to quickly pinpoint issues, and often include links to standards.

tota11y

tota11y is an open source “bookmarklet” which modifies the currently-loaded page in-place, and highlights a number of accessibility issues.

WAVE

WAVE is a proprietary (but gratis) browser extension which can highlight a large number of issues.

In Continuous Integration

A number of automated tools are available for assessing glaring accessibility issues across a number of pages at once, usually with many configurable options.

Lighthouse

Lighthouse, which provides automated assessment of basic accessibility issues in addition to search engine automation, page performance, and other best practices.

Hint

Specifically, foo-software/lighthouse-check-action is run on selected pages from the generated documentation site.

Pa11y CI

Pa11y CI is a command line tool which can check a number of accessibility standards. It is most effective when paired with a sitemap.xml, discussed above.

Hint

This approach is more involved: for this site, we’ve written some custom runners which:

  • start a static file server locally with the docs site

  • run pa11y-ci against the site’s sitemap.xml

  • read known failures in a a11y-roadmap.txt file

  • generate HTML reports (including all errors)

  • perform some light parsing to generate some short reports

  • archive the reports in CI