Accessibility#
Creating and publishing content that does not exclude disabled users is a complex and iterative task.
While there is no one-size-fits-all solution to maintaining accessible content, the PyData Sphinx Theme and this 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!
What We’ve Done#
Metadata#
Several of our documentation pages contain metadata (i.e., .. meta::
directives
in reStructuredText) giving summaries of the page contents. If you notice a
page that lacks metadata, please open a pull request to add it!
Colors#
Our default code highlighting styles are
a11y-high-contrast-light
anda11y-high-contrast-dark
from Quansight-Labs/accessible-pygments. These styles are designed to meet WCAG 2 AA or AAA contrast requirements. If you don’t like the look of our default code highlighting styles, there are several more to choose from at Quansight-Labs/accessible-pygments.We recently revisited the PyData Sphinx theme color palette to ensure that the colors we use meet WCAG 2 AA or AAA contrast requirements.
We also re-defined our
primary
andsecondary
colors to be more accessible and distinct from semantic colors used to denote success, warning, info, and danger contexts or information.We simplified the color palette and removed some colors that were problematic in meeting WCAG 2 AA or AAA contrast requirements and for certain types of colorblindness.
We have improved how we assign text colors to interactive elements such as buttons and dropdowns to ensure that they meet WCAG 2 AA or AAA contrast requirements.
To learn more about the PyData Sphinx Theme colors, check the PyData Sphinx Theme Design System section.
Testing and auditing#
We have also added automated tests and conducted manual audits. See Accessibility checks and manual auditing.
What You Can Do#
Site configuration#
The following sections include recommendations for settings in the conf.py
file that can positively 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
In your conf.py
file,
specifying the language your docs are written in
will propagate to the top-level HTML
tag.
language = "en"
Add a 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 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}"
Logo best practices#
We recommend that you support dark mode by providing either a single version of your logo that works well in both light and dark modes, or two separate versions. We also recommend that you supply alt text for your logo in any place that the image appears by itself without a visible text version of the logo. For example, if you have the Python snake logo all by itself, you should supply the alt text “Python,” whereas if you have the snake image followed by the word “Python” in visible, regular, copy-paste-able text, then you do not need to provide alt text.
These recommendations are covered in detail at the page Branding and logo
Test and inspect your site#
Several browser tools exist for interactively debugging the accessibility of a single page at a time and can be useful during the content development cycle.
Non-interactive tools also exist for use with CI (continuous integration).
Browser tools#
Most major browsers, including Firefox and Chrome, have built-in accessibility tools as part of their web developer tools. These tools can help to quickly identify accessibility issues and often include links to standards:
There are also a few browser extensions that some of the maintainers of this theme use when working to make websites more accessible. Some of these include:
We have also found Polypane to be a great tool (but it is not free and requires a license).
Continuous Integration tools#
Two accessibility testing tools designed for continuous integration are Lighthouse CI and Pa11y CI.
The foo-software/lighthouse-check-action may be helpful if the code for your site is hosted on GitHub.
If you are curious about how we do accessibility CI for this theme, refer to the page Accessibility checks and manual auditing.
Warning
Note that automated testing and extensions such as the ones mentioned above will at best catch 30-40% of accessibility issues. They are not a replacement for manual testing. Having a perfect score on any of these tools does not mean that your site can be used by disabled users. Instead, a good score signals that your site follows some best accessibility practices.