可访问性#

创建和发布不排除残疾用户的内容是一项复杂且迭代的任务。

虽然没有一种放之四海而皆准的解决方案来维护可访问的内容，但 PyData Sphinx 主题和此文档站点使用了一些技术来避免常见的内容缺陷。

备注

非常欢迎识别或修复此主题或站点可访问性问题的议题和拉取请求！

做了什么#

元数据#

许多文档页面都包含元数据（即 reStructuredText 中的 .. meta:: 指令），提供页面内容的摘要。如果您发现某个页面缺少元数据，请打开拉取请求添加它！

颜色#

默认代码高亮样式是来自 Quansight-Labs/accessible-pygments 的 a11y-high-contrast-light 和 a11y-high-contrast-dark。这些样式旨在满足 WCAG 2 AA 或 AAA 对比度要求。如果您不喜欢默认的代码高亮样式，Quansight-Labs/accessible-pygments 上还有更多选择。
最近重新审视了 PyData Sphinx 主题的调色板，以确保使用的颜色符合 WCAG 2 AA 或 AAA 对比度要求。
还重新定义了 primary 和 secondary 颜色，使其更具可访问性，并与用于表示成功、警告、信息和危险上下文或信息的语义颜色区分开来。
简化了调色板，并移除了一些在满足 WCAG 2 AA 或 AAA 对比度要求以及某些类型的色盲方面存在问题的颜色。
改进了为按钮和下拉菜单等交互元素分配文本颜色的方式，以确保它们符合 WCAG 2 AA 或 AAA 对比度要求。

要了解更多关于 PyData Sphinx 主题颜色的信息，请查看 PyData Sphinx 主题设计系统部分。

测试与审计#

还添加了自动化测试并进行了手动审计。请参阅无障碍检查与手动审核。

您可以做什么#

站点配置#

以下部分包括对 conf.py 文件中设置的建议，这些设置可以积极影响此主题和 Sphinx 生成内容的可访问性。

自然语言#

如果不采用更健壮的国际化方法，至少指定基线自然语言将有助于辅助技术识别内容是否使用读者理解的语言。

提示

在您的conf.py文件中，指定文档编写的语言将传播到顶层的 HTML 标签。

language = "en"

添加站点地图#

站点地图通常从名为 sitemap.xml 的文件提供，是一种广泛使用的方法，用于告诉搜索引擎和辅助技术等程序不同内容在网站上的位置。

如果使用ReadTheDocs等服务，这些文件将自动为您创建，但对于下面的一些其他方法，使用 sphinx-sitemap 等工具在本地或 CI 中生成 sitemap.xml 很方便。

提示

对于简单的站点（没有额外的语言或版本），确保 sphinx-sitemap 已安装在您的文档环境中，并修改您的 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 最佳实践#

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.

这些建议在页面品牌标识与徽标中有详细说明。

测试和检查您的站点#

存在多种浏览器工具，可以交互式地一次调试单个页面的可访问性，在内容开发周期中非常有用。

非交互式工具也可用于CI（持续集成）。

浏览器工具#

大多数主流浏览器，包括 Firefox 和 Chrome，都内置了作为其 Web 开发者工具一部分的可访问性工具。这些工具可以帮助快速识别可访问性问题，并通常包含指向标准的链接：

还有一些浏览器扩展，本主题的一些维护者在努力使网站更具可访问性时使用。其中一些包括：

还发现Polypane是很棒的工具（但它不是免费的，需要许可证）。

持续集成工具#

两个专为持续集成设计的可访问性测试工具是Lighthouse CI和Pa11y CI。

如果您的站点代码托管在GitHub上，foo-software/lighthouse-check-action可能会有所帮助。

如果您对我们如何为此主题进行可访问性CI感到好奇，请参阅页面无障碍检查与手动审核。

警告

请注意，自动化测试和上述扩展最多只能捕捉30-40%的可访问性问题。它们不能替代手动测试。在任何这些工具上获得完美分数并不意味着您的站点可以被残疾用户使用。相反，良好的分数表明您的站点遵循了一些最佳可访问性实践。