变更日志

另请参阅

如何升级

3.0.1

  • 在选择器中使用黑色文本。

3.0.0

最终版本。

3.0.0rc4

修复

  • 在导航栏中聚焦“搜索文档”输入框时触发“Read the Docs 搜索插件”。

3.0.0rc3

修复

  • 如果隐藏版本是当前活动版本，则在选择器中显示它

3.0.0rc2

新增

  • 在文档标题下方（左上方）渲染版本和语言选择器。这可以通过新的主题选项 version_selector 和 language_selector 控制。

3.0.0rc1

新增

  • 添加了对 Sphinx 8 的支持。

  • 添加了对 Python 3.12 的支持。

  • 添加了对 docutils >0.18, <0.22 的支持。

  • 使用所有以 READTHEDOCS_ 开头的环境变量填充 html_context。

弃用

  • 放弃对 Sphinx <6.0 的支持。

  • 放弃对 Python <3.8 的支持。

  • analytics_id 和 analytics_anonymize_ip 已弃用，请改用 sphinxcontrib-googleanalytics。

  • 放弃对所有版本的 Internet Explorer 的支持。

  • 在定义 html_theme_path 时发出警告。这是一个不再需要的旧配置。

  • extra_css_files 已弃用，将在未来版本中删除支持。

2.1.0rc2

新增

  • 添加了 flyout_display 选项以显示浮出层 attached（侧边栏底部）或 hidden（默认）。

2.1.0rc1

新增

  • 使用新的 readthedocs-addons-data-ready Read the Docs 插件 CustomEvent 渲染菜单版本/语言选择器（浮出层）。

弃用

  • 删除 html5shiv。

2.0.0

新增

  • 支持 Sphinx 版本 6.x 和 7.x

  • 支持 docutils <=0.20

弃用

  • HTML4 编写器现已正式弃用。如果您的项目配置仍然使用 HTML4 编写器，则会抛出错误。

  • 已删除对 Sphinx 版本 < 5.0 的支持。

  • 此外，我们的支持依赖项将与我们最低支持的 Sphinx 版本（版本 5.0）的依赖项相匹配：Python >= 3.6 和 docutils > 0.14 且 < 0.19

1.3.0

新增

  • 放宽了要求以包含 Sphinx 版本 7.0

1.2.2

修复

  • 需要 sphinxcontrib-jquery>=4,<5 (#1446)

新增

  • :menuselection: 的样式 (#1426)

1.2.1

修复

  • 在使用最新 sphinxcontrib-jquery 版本时正确加载 jQuery (#1448)

1.2.0

依赖项更改

  • 支持 docutils 0.18。(#1381)

  • 添加了对 Sphinx 6 的支持

  • 添加了 sphinxcontrib-jquery 作为依赖项 (#1385 #1421)

  • Python 3.11 已正式支持并经过测试。(#1395)

  • Python 3.4 和 3.5 已正式不再支持 (#1395)

更改

  • 在 Sphinx 6+ 中自动使用 sphinxcontrib-jquery (#1399)

  • 在可用时使用新的上下文变量 logo_url、favicon_url 和 root_doc (#1405)

  • 更新了翻译：法语、匈牙利语、克罗地亚语

  • 添加了翻译：丹麦语、中文（台湾）

Sphinx<4 用户须知

如果您无法使用更新的 Sphinx 版本，则至少应确保您正在使用其主要版本的最新版本。目前，这些是 Sphinx 1.8.6 和 2.4.5。较旧的版本可能会安装不受支持的多个依赖项版本，包括 Jinja2 和 docutils。

已知问题

在某些情况下，jQuery 不会在 Read the Docs 上使用 Sphinx 6 加载。解决方法：您需要在 conf.py 中的 extensions 中添加 sphinx_rtd_theme。有关更新，请参阅 readthedocs.org 问题 #9654。

1.1.1

修复

  • 修复交叉引用时的换行错误 (#1368)

1.1.0

依赖项更改

许多文档项目依赖于 sphinx-rtd-theme 而不指定主题版本（未固定），同时还依赖于未固定的 Sphinx 版本。理想情况下，最新版本的 sphinx-rtd-theme 始终支持最新版本的 Sphinx，但这现在已得到保证。

此版本为直接依赖项 Sphinx 和 docutils 添加了上限，这将防止与 Sphinx 和 docutils 可能不兼容的未来版本混合使用。

  • 支持的 Sphinx 版本：1.6 至 5.2.x

  • Sphinx<6 (#1332)

  • docutils<0.18（不变，但将在即将发布的版本中更新）

功能

  • 更美观的 <kbd> 样式 (#967)

  • 面包屑的新样式 (#1073)

修复

  • Sphinx 版本中的后缀导致构建错误 (#1345)

  • 包含多个段落的表格单元格格式错误 (#289)

  • API 文档中定义列表渲染错误 (#1052)

  • 引用样式不正确 (#1078)

  • 长 URL 没有换行 (#1193)

次要更改

  • Sphinx 5.2 添加到测试矩阵 (#1348)

  • Python 3.10 添加到测试矩阵 (#1334)

  • 开发的补充 Docker 设置 (#1319)

  • 大部分 setup.py 迁移到 setup.cfg (#1116)

  • Jinja2 上下文变量 sphinx_version_info 现在是 (major, minor, -1)，修订版组件始终为 -1。原因：它很复杂。(#1345)

不兼容更改

此版本中没有已知的不兼容更改。对 docutils 版本 0.18 和 0.19 的支持计划在我们的下一个版本中提供。

1.0.0

不兼容更改

  • 最低支持的 Python 版本现在为 2.7 或 3.4 及更高版本 (#1093)

  • 最低支持的 Sphinx 版本现在为 1.6 (#1091)

已弃用

  • 对 Sphinx 的 HTML4 编写器的支持已弃用，将在 2.0 版中删除 (#1091)

功能

  • 添加对 Sphinx 4.x 的支持 (#1123)

  • 添加对 Docutils 0.17 的支持 (#1185 和 #1199)

  • 修复了 IE11 上的徽标缩放问题 (#1183)

  • 添加了对徽标作为 URL 的支持 (#1171)

  • 在移动设备上对齐顶部和侧边导航背景颜色 (#1132)

  • 添加了对深度 TOC 级别（目录级别）的支持 (#1089)

  • 更新了中文、荷兰语、爱沙尼亚语、法语、德语、意大利语、立陶宛语、波斯语、波兰语、葡萄牙语、俄语、西班牙语、瑞典语和土耳其语语言环境的翻译

此版本中添加了许多辅助功能

  • 允许键盘切换菜单展开 (#1167)

  • 允许键盘激活永久链接 (#1162)

  • 在按钮上显示键盘焦点 (#1161)

  • 在菜单中维护 aria-expanded 和 .current (#1151)

  • 尊重上一个/下一个按钮的 Tab 键顺序 (#1051)

修复

  • 更新了 Google Analytics 集成 (#1129)

  • 在 Sphinx 2+ HTML4 编写器上添加分类器分隔 (#1192)

  • 添加了页脚中缺少的空格字符 (#1188)

  • 修复二级及以上元素导航右侧填充问题（#1068）

  • 修复导航展开按钮大小问题（#1067）

  • 包装内联字面量（#1050）

  • 修复 aria 标签（#1056）

  • 不要切换导航终端节点（#1049）

  • 修复 `<pre>` 溢出问题（#1220）

  • 修复 `<dl>` 内部的字面量/引用样式（#1088）

其他更改

  • 更新 npm 开发依赖项（#1096）

  • 不要求从源代码构建时使用 npm（#1039）

  • 对于 singlehtml 构建器，使用常规 toctree 而不是 toc（#507）

  • 清理模板中的空白字符（#1060）

0.5.2

日期:

2021年4月5日

注意

此提交不会出现在 `master` 中，但直接从 `0.5.1` 分支出来以最大程度地减少问题。下一个完整版本将包含之前合并的所有 PR。

  • 依赖于 docutils < 0.17（#1113）

0.5.1

日期:

2021年1月4日

修复

  • 在索引中正确设置 `url_root`（#1025）

  • 不要在非搜索页面中加载 `language_data.js`（#1021）

  • 隐藏任何类似 `singlehtml` 构建器的搜索框（#975）

  • 修复 `vcs_pageview_mode` 模板参数（#1010）

  • 将 nex/prev 图标标记为 aria-hidden（#1007）

  • 使用格式良好的 XML 语法（#1006）

  • 页脚：如果可用，则显示 `commit` 和 `last_updated`（#897）

  • 搜索页面：不要显示“在…上编辑”链接（#935）

新功能

  • 新的主题选项，在使用 Google Analytics 时启用匿名 IP 地址（#889）

其他更改

  • `canonical_url` 选项已弃用，取而代之的是 Sphinx 的 `html_baseurl`（#1003）

  • 将 `contentinfo` 块添加到 `footer.html` 模板（#896）

  • 使版权模板与 sphinx 的基本模板匹配（#933）

  • 打包：包含 `bin/preinstall.js`（#1005）

0.5.0

日期:

2020年6月17日

修复

  • 修复项目符号列表间距以尊重简单/复杂列表样式

0.5.0rc2

日期:

2020年6月5日

修复

  • 修复遗漏的简单定义列表问题

  • 将 FOUT 改回 FOIT

  • 修复列表、嵌套列表和嵌套内容的多个边距问题

  • 将冒号放回字段列表

0.5.0rc1

日期:

2020年5月6日

修复

  • 修复使用 Sphinx HTML5 编写器时外观不同的许多样式问题

其他更改

  • 在导航区域周围添加 `navigation` 模板块。

  • 添加了使用 Babel 的 i18n 支持

  • 为 10 种新语言添加了翻译

  • 将构建系统从 Grunt 及其相关工具迁移到 Webpack

  • 删除 Modernizr，但保留 html5shiv（#724、#525）

0.4.3

日期:

2019年2月12日

新功能

修复

  • 修复加载时滚动到侧边栏中活动项的问题（#214）

  • 为代码和字面量块设置标题链接样式

  • 修复 autodoc“引发”和“返回”的不一致字体大小和行高问题（#267）

  • 修复 `last_updated` 通知出现在与版权通知同一行的问题（#704）

其他更改

0.4.2

日期:

2018年10月5日

新功能

修复

  • 在 `` 上设置基本字体大小（#668）

  • 修复 Sphinx-1.8 中 HTML 搜索无法工作的问题（#672）

其他更改

  • 使用 twine 将签名包上传到 PyPI（#651）

  • 不要在版权声明末尾强制使用句点 (666)

0.4.1

日期:

2018年7月27日

新功能

修复

  • Liberation Mono 的行高调整（#656）

其他更改

  • 添加 Sphinx 作为依赖项

0.4.0

此版本对在 Read the Docs 上使用主题时包含 JS 和 CSS 的方式进行了一些更改。

新功能

修复

  • 不要依赖 readthedocs.org 获取 CSS/JS（#614）

  • 左侧导航的颜色可访问性改进

其他更改

  • 在 JavaScript 和 CSS 的顶部写入主题版本和构建日期

  • 更改代码和字面量以使用本机字体堆栈（#612）

  • 修复一些小的样式问题

0.3.1

修复

  • 恢复 #576 的一部分，该部分导致版本选择器菜单出现显示问题

  • 针对 0.3.0 之前的版本进行向后兼容性修复（#623）

  • 修复 mkdocs 版本选择器（#622）

  • 添加打开列表间距（#591）

  • 修复表格居中问题（#599）

0.3.0

**注意**：此版本在 readthedocs.org 上使用时导致了一些 JavaScript 不兼容性

新功能

  • 添加 html 语言属性

  • 允许为样式表设置“rel”和“title”属性（#551）

  • 添加样式化外部链接的选项

  • 添加 github、gitlab、bitbucket 页面参数选项

  • 添加 pygments 支持

  • 添加 setuptools 入口点，允许直接将 `sphinx_rtd_theme` 用作 Sphinx 的 `html_theme`。

  • 将语言添加到 JS 输出变量

修复

  • 修复一些 HTML 警告和错误

  • 修复许多样式问题

  • 修复许多侧边栏故障

  • 修复行号间距以与代码行对齐

  • 隐藏自动创建页面的“编辑”链接

  • 包含主题中缺少的字体文件

其他更改

  • 我们文档的重大改进

  • 压缩我们的 Javascript 文件

  • 更新依赖项

0.2.4

  • 另一个修补程序，用于处理 Spinx 之外的额外构建器，例如 Read the Docs Sphinx 扩展中的 singlehtml 构建器

0.2.3

  • 通过检查模板中的构建器，临时修补 Sphinx 中 `singlehtml` 构建器的问题。

0.2.2

  • 回滚 0.2.1 中的 toctree 修复（#367）。这没有解决问题，并在 toctrees 显示中引入了另一个错误。

0.2.1

  • 将 `rel` HTML 属性添加到指向前后页的页脚链接。

  • 修复 Sphinx singlehtml 构建器引起的 toctree 问题（#367）

0.2.0

  • 在模板中的 `body` 块之后添加 `comments` 块

  • 添加了“在 GitLab 上编辑”支持

  • 许多错误修复

0.1.10-alpha

注意

这是一个预发布版本

  • 删除 Sphinx 依赖项

  • 修复移动设备上汉堡包菜单的显示

  • 在模板中添加 `body_begin` 块

  • 添加了 `prev_next_buttons_location`

0.1.9

  • 修复了间歇性的滚动条可见性错误。此更改对主题的布局 HTML 引入了向后不兼容的更改。这应该只对使用直接后代选择器覆盖了导航元素样式的派生主题造成问题。有关更多信息，请参阅 #215。

  • 修复了 Safari 滚动溢出错误

  • 版本已添加到导航标题

  • 如果使用 RTD，则修订 ID 已添加到文档页脚

  • 添加了一个额外的块 `extrafooter` 以允许在文档页脚块中添加额外内容

  • 修复了 modernizr URL

  • 代码块、图形标题和导航元素上的少量显示样式更改

0.1.8

  • 开始保留变更日志 :)

  • 支持侧边栏中的三级和四级标题

  • 添加对 Sphinx 1.3 的支持

  • 为 Sphinx toctree 中的 `:caption:` 添加侧边栏标题

  • 清理侧边栏滚动行为，使其永远不会滚动到视图之外