Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* ♿ Add basic links style * Update link styles for sidebars * ♿️ Replace more links - sidebars and TOC * ♿ Add basic links style * Update link styles for sidebars * ♿️ Replace more links - sidebars and TOC * ♿️ Update navigation links style * 📝 Update accessibility docs * ♿ Update more links styles * Update icon links style * Remove duplicate styles * 💄 Update base link style * 💄 Update navigation styles * Apply suggestions from code review Co-authored-by: Daniel McCloy <dan@mccloy.info> * Fix sidebar links - hover * 🚚 Move helpers into separate files * ♿ Ensure current styles are current and not active * ♿ Ensure current links are consistent * ♿ Fix TOC hover links * 💄 Ensure prev-next are purple on hover * Update active + hover style * ♿ Fix hover on dropdowns * Unify link styles -icons and navigation * Ensure navbar links behave under hover * Add temporary focus style * Remove underline from breadcrumbs * remove EnOSlib (temporarily) to restore doc build * remove expectation of EnOSlib warning * 💄 Remove visited colour * Add focus style to search box --------- Co-authored-by: Daniel McCloy <dan@mccloy.info>
- Loading branch information
Showing
27 changed files
with
648 additions
and
486 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,142 @@ | ||
# 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` and | ||
`a11y-high-contrast-dark` from https://github.com/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 https://github.com/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` and `secondary` 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. | ||
|
||
## 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](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html), | ||
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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language) will propagate to the top-level `HTML` tag. | ||
|
||
```python | ||
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](https://readthedocs.com), 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](https://pypi.org/project/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`: | ||
|
||
```python | ||
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 | ||
|
||
If you use both light and dark themes, it's best to provide a logo that works well in both or to provide an alternative for the dark theme. | ||
If you have a logo, you can add alt-text to it by adding the following to your | ||
`conf.py`: | ||
|
||
```python | ||
"logo": { | ||
"text": "PyData Theme", | ||
"image_dark": "_static/logo-dark.svg", | ||
"alt_text": "PyData Theme home", | ||
}, | ||
``` | ||
|
||
Note the use of "home" in the alt text to indicate that the logo is also a link to the home page. | ||
|
||
### In the Browser | ||
|
||
Several 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](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector) | ||
and [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference), | ||
have accessibility tools built-in as part of their web developer tools. | ||
These tools can help to quickly identify accessibility issues and often include links to standards. | ||
|
||
#### tota11y | ||
|
||
[tota11y](https://khan.github.io/tota11y/#Installation) is an open source | ||
"bookmarklet" which modifies the currently-loaded page in place and highlights | ||
several accessibility issues. | ||
|
||
#### WAVE | ||
|
||
[WAVE](https://wave.webaim.org/extension/) is a proprietary (but _gratis_) | ||
browser extension which can highlight multiple issues. | ||
|
||
:::{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 and having a perfect score on any of these tools does not mean that | ||
the site can be used by disabled users but instead signals that it follows some accessibility best practices. | ||
::: | ||
|
||
### In Continuous Integration | ||
|
||
Several automated tools are available for assessing _glaring_ accessibility | ||
issues across some pages at once, usually with many configurable options. | ||
|
||
#### Lighthouse | ||
|
||
[Lighthouse](https://developers.google.com/web/tools/lighthouse) provides an 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](https://github.com/foo-software/lighthouse-check-action) | ||
is run on selected pages from the generated documentation site. | ||
::: |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.