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