更新日志

发布 9.0.1 (开发中)

修复的 Bug

发布 9.0.0 (发布于 2025 年 11 月 30 日)

依赖项

不兼容的变更

  • #13639:SphinxComponentRegistry.create_source_parser() 不再有 app 参数,而是接受 configenv。Adam Turner 的补丁。

  • #13679:源文件中不可解码的字符现在会引发错误。自 Sphinx 2.0 以来,此类字节已被替换为“?”并记录警告。Adam Turner 的补丁。

  • #13751, #14089:sphinx.ext.autodoc 已进行了大量重写,在边缘情况下可能存在一些不兼容的更改,尤其是在扩展与 autodoc 内部机制交互时。已添加 autodoc_use_legacy_class_based 选项以使用旧版 (9.0 之前) 的 autodoc 实现。Adam Turner 的补丁。

  • #13355:不要在搜索索引中包含转义的标题内容。Will Lachance 的补丁。

已弃用

  • 13627:弃用剩余的公共 .app 属性,包括 builder.appenv.appevents.appSphinxTransform.app。Adam Turner 的补丁。

  • #13637:弃用 Parser 对象的 set_application() 方法。Adam Turner 的补丁。

  • #13644:弃用 Parser.configenv 属性。Adam Turner 的补丁。

  • #13665:弃用对非 UTF-8 源编码的支持,计划在 Sphinx 10 中删除。Adam Turner 的补丁。

  • #13682:弃用 sphinx.io。Sphinx 不再使用 sphinx.io 类,已将其替换为标准 Python I/O。整个 sphinx.io 模块将在 Sphinx 10 中删除。Adam Turner 的补丁。

  • #13631:从 Sphinx 11 开始,sphinx.environment.adapters.toctree.global_toctree_for_doc()sphinx.environment.BuildEnvironment.get_and_resolve_doctree() 将需要一个 tags 关键字参数。从 Sphinx 9 开始可以可选地传递。Adam Turner 的补丁。

新增功能

  • #13332:添加 doctest_fail_fast 选项,以便在第一次测试失败后退出。Till Hoffmann 的补丁。

  • #13439:linkcheck:允许在每次重定向时发出警告,使用 linkcheck_allowed_redirects = {}。Adam Turner 和 James Addison 的补丁。

  • #13497:支持目录中的 C 领域对象。

  • #13500:LaTeX:添加对 fontawesome6 软件包的支持。Jean-François B. 的补丁。

  • #13509:autodoc:检测 typing_extensions.overloadfinal() 装饰器。Spencer Brown 的补丁。

  • #13535:html 搜索:更新到最新版本的 Snowball (v3.0.1)。Adam Turner 的补丁。

  • #13647:LaTeX:允许更多表格嵌套的情况。Jean-François B. 的补丁。

  • #13657:LaTeX:支持 CSS3 长度单位。Jean-François B. 的补丁。

  • #13684:intersphinx:为远程清单添加基于文件的缓存。缓存目录的位置不应外部依赖,因为它在未来的版本中可能会在没有通知或警告的情况下更改。Adam Turner 的补丁。

  • #13805:LaTeX:添加对 fontawesome7 软件包的支持。Jean-François B. 的补丁。

  • #13508:autodoc:对 PEP 695 类型别名的初步支持。Martin Matouš、Jeremy Maitin-Shepard 和 Adam Turner 的补丁。

  • #14023:添加新的 mathjax_config_path 选项,用于从文件中加载 MathJax 配置。Randolf Scholz 和 Adam Turner 的补丁。

  • #14046:linkcheck:添加 linkcheck_case_insensitive_urls 选项,允许对特定 URL 模式进行不区分大小写的 URL 比较。这对于链接到规范化 URL 大小写(例如 GitHub)的网站或不区分大小写的服务器很有用。Fazeel Usmani 和 James Addison 的补丁。

  • #14075:autosummary:在导入异常堆栈跟踪中提供更多上下文。Philipp A. 的补丁。

  • #13468:向 sphinx.ext.duration 添加配置选项。Erik Bedard 和 Adam Turner 的补丁。

  • #14022:在 sphinx.ext.mathjax 扩展中,默认使用 MathJax v4,之前是 v3。要继续使用旧版本,请设置 mathjax_path 选项。还添加了新的 mathjax4_config 选项来配置 MathJax v4。请注意,MathJax v3 大部分与 MathJax v4 兼容,因此现有的 mathjax3_config 设置无需更改。Matthias Geier 的补丁。

  • #14029:intersphinx:修复格式字符串插值错误。Matthieu de Cibeins 的补丁。

  • #13894:将 source_code_parser 类型添加到 suppress_warnings,用于分组与 C 和 C++ 解析器相关的问题。Valentin H. 的补丁。

修复的 Bug

  • #13926:同一规范类型存在多个 py:type 指令不再导致虚假的重复对象描述警告。Jeremy Maitin-Shepard 的补丁。

  • #1327:LaTeX:如果 tabularcolumns 指定自动宽度(LRCJ),使用 longtable 的表格会引发错误。Jean-François B. 的补丁。

  • #3447:LaTeX:为 PDF 的表格分配 longtable 类时,它可能会“水平”渲染并溢出右边距。Jean-François B. 的补丁。

  • #8828:LaTeX:向 longtable 单元格添加脚注会导致表格占用整个宽度。Jean-François B. 的补丁。

  • #11498:LaTeX:单元格中的表格如果行数过多则无法构建。Jean-François B. 的补丁。

  • #11515:LaTeX:longtable 不允许嵌套表格。Jean-François B. 的补丁。

  • #11973:LaTeX:表格标题中的链接在 PDF 中不起作用。Jean-François B. 的补丁。

  • #12821:LaTeX:节标题中的 URL/链接应在 PDF 中渲染。Jean-François B. 的补丁。

  • #13369:正确解析和交叉引用解包的类型注解。Alicia Garcia-Raboso 的补丁。

  • #13528:为 py:deco 添加波浪号 ~ 前缀支持。Shengyu Zhang 和 Adam Turner 的补丁。

  • #13597:LaTeX:嵌套在合并单元格中的表格会导致无效的 LaTeX 标记,且无法构建 PDF。Jean-François B. 的补丁。

  • #13619:LaTeX:对象签名中的脚注可能导致 PDF 中重复的脚注(通常在 latex_show_urls = 'footnote' 时)。Jean-François B. 的补丁。

  • #13635:LaTeX:如果单元格包含表格,则后续表格单元格的行着色将关闭。Jean-François B. 的补丁。

  • #13685:gettext:正确忽略尾随反斜杠。Bénédikt Tran 的补丁。

  • #13712:intersphinx:不要为非数字版本添加“v”前缀。Szymon Karpinski 的补丁。

  • #13688:HTML builder:将属性类型注解的 <em class="property"> 替换为 <span class="property">,以改进 语义 HTML 结构。Mark Ostroth 的补丁。

  • #13812 (讨论):LaTeX:长 confval 值在 PDF 中不会在空格处换行。Jean-François B. 的补丁。

  • #10785:Autodoc:允许项目中定义的类型别名在用作类型注解时正确地进行交叉引用。这使得以 :py:data: 形式文档化的对象可以在函数签名中超链接。

  • #13858:doctest:doctest 块现在正确地添加到由配置变量 doctest_test_doctest_blocks 定义的组中。

  • #13885:Coverage builder:修复警告缺少模块时的 TypeError。Damien Ayers 的补丁。

  • #13929:重复的方程标签警告现在有一个新的警告子类型 ref.equation。Jared Dillard 的补丁。

  • #13935:autoclass:在某些情况下,根据 autodoc 处理顺序,父类成员不再被视为直接定义。Jeremy Maitin-Shepard 的补丁。

  • #13939:LaTeX:分页符可能会将提醒标题与内容分离。Jean-François B. 的补丁。

  • #14004:修复在 PEP 604 联合语法 (Alias | Type) 中出现的 autodoc_type_aliases。Tamika Nomara 的补丁。

  • #14059:LaTeX:脚注导致 pdflatex 在法语中出错(自 2025 年 6 月下旬上游更改 LaTeX babel-french 以来)。Jean-François B. 的补丁。

  • #13916:HTML 搜索:页面加载时不要清除 URL 中的文本片段。Harmen Stoppels 的补丁。

  • #13944:autodoc:以人类可读的形式显示导入时的回溯。Florian Best 的补丁。

  • #14006:支持非 base64 编码的带有数据 URI 的图像。Shengyu Zhang 和 Adam Turner 的补丁。

  • #12797:修复从 Generic 和 autodoc 模拟类继承时出现的 Some type variables (...) are not listed in Generic[...] TypeError。Ikor Jefocur 和 Daniel Sperber 的补丁。

  • #13945:autodoc:通过使用 FORWARDREF annotationlib 格式,修复注释中未定义名称的处理。Rui Pinheiro 和 Adam Turner 的补丁。

  • #14067:EPUB:统一清单项中的路径分隔符为正斜杠;解决 Windows 上清单中的重复项。Akihiro Takizawa 的补丁。

  • #13741:text builder:修复处理 CSV 表格时的无限循环。Bénédikt Tran 的补丁。

  • #13217:删除 js:function 参数和错误中的额外括号。Shengyu Zhang 的补丁。

测试

以前的版本