.. _accessibility:

.. meta::
    :description lang=en:
        The features and plans for addressing accessibility concerns on pydata-sphinx-theme

*************
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 <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::

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

    .. code-block:: python

        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 <https://readthedocs.com>`__, 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 <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``:

    .. code-block:: 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}"


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 <https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector>`__
and `Chrome <https://developers.google.com/web/tools/chrome-devtools/accessibility/reference>`__
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 <https://khan.github.io/tota11y/#Installation>`__ is an open source
"bookmarklet" which modifies the currently-loaded page in-place, and highlights
a number of accessibility issues.


WAVE
----

`WAVE <https://wave.webaim.org/extension/>`__ 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 <https://developers.google.com/web/tools/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 <https://github.com/foo-software/lighthouse-check-action>`__
    is run on selected pages from the generated documentation site.


Pa11y CI
--------

`Pa11y CI <https://github.com/pa11y/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
