无障碍性#
创建和发布不排斥残疾用户的內容是一项复杂且反复的任务。
虽然没有万能的解决方案来维护可访问的內容,但 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 对比度要求。
您可以做什么#
站点配置#
以下部分包含对 conf.py
文件中设置的建议,这些设置可以积极影响此主题和 Sphinx 通常生成的內容的可访问性。
自然语言#
如果不使用更强大的 国际化方法,至少指定基础自然语言将有助于辅助技术识别內容是否为读者理解的语言。
添加站点地图#
站点地图通常存储在名为 sitemap.xml
的文件中,这是一种广泛采用的方法,用于告诉搜索引擎和辅助技术等程序不同內容在网站上的位置。
如果使用 ReadTheDocs 等服务,这些文件将自动为您创建,但对于以下某些其他方法,在本地或在 CI 中使用 sphinx-sitemap 等工具生成 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}"
标识最佳实践#
如果您同时使用浅色和深色主题,最好提供一个在两种主题中都能良好显示的标识,或者为深色主题提供替代标识。如果您有标识,可以通过在您的 conf.py
中添加以下内容来添加替代文本:
"logo": {
"text": "PyData Theme",
"image_dark": "_static/logo-dark.svg",
"alt_text": "PyData Theme home",
},
请注意使用“home”作为替代文本,以指示标识也是首页的链接。
在浏览器中#
存在一些浏览器内工具,用于交互式调试单个页面的可访问性,这些工具在內容开发周期中可能很有用。
内置工具#
大多数主流浏览器,包括 Firefox 和 Chrome,都将可访问性工具内置到其网页开发者工具中。这些工具可以帮助快速识别无障碍性问题,并且通常包含指向标准的链接。
tota11y#
tota11y 是一个开源的“书签工具”,它会修改当前加载的页面,并突出显示一些无障碍性问题。
WAVE#
WAVE 是一个专有(但免费)的浏览器扩展,可以突出显示多个问题。
警告
请注意,自动化测试和上述扩展最多只能发现 30-40% 的无障碍性问题。它们不能替代人工测试,任何这些工具上的完美得分并不意味着该站点可以被残疾用户使用,而只是表明它遵循了一些无障碍性最佳实践。
在持续集成中#
存在一些自动化工具,用于评估一些页面中的明显无障碍性问题,通常具有许多可配置选项。
Lighthouse#
Lighthouse 提供对基本无障碍性问题、搜索引擎自动化、页面性能和其他最佳实践的自动化评估。
提示
具体来说,foo-software/lighthouse-check-action 在生成的文档站点的选定页面上运行。