Sphinx 4.0

发布 4.0.3 (发布于 2021 年 7 月 5 日)

新增功能

  • C，添加 C23 关键字 _Decimal32、_Decimal64 和 _Decimal128。

  • #9354: C，添加 c_extra_keywords 以允许在解析期间使用用户定义的关键字。

  • 恢复移除 sphinx.util:force_decode()，以便在 5.0 期间恢复一些第三方扩展的可用性

修复的 Bug

  • #9330: 变更集域：包含列表内容的 versionchanged 将在 PDF 构建期间导致错误

  • #9313: LaTeX: 包含合并单元格的复杂表格自 4.0 版本以来已损坏

  • #9305: LaTeX: 反斜杠可能导致日语引擎在 PDF 构建时出现不正确的自由列表错误

  • #9354: C，从关键字列表中删除特殊宏名称。另请参阅 c_extra_keywords。

  • #9322: 在 PropagateDescDomain 转换中引发 KeyError

发布 4.0.2 (发布于 2021 年 5 月 20 日)

依赖项

  • #9216: 支持 jinja2-3.0

不兼容的变更

  • #9222: 更新 Underscore.js 到 1.13.1

  • #9217: manpage: 默认情况下停止在构建手册页时创建节目录（参见 man_make_section_directory）

修复的 Bug

  • #9210: viewcode: 如果在并行构建时发现不可导入的模块，则崩溃

  • #9240: 如果不支持 pending_xref_condition 节点的扩展安装了缺失引用处理程序，则会引发未知节点错误

发布 4.0.1 (发布于 2021 年 5 月 11 日)

修复的 Bug

  • #9189: autodoc: 当从类的属性生成签名时引发 ValueError 时崩溃

  • #9188: autosummary: 如果将列表值设置为 autosummary_generate，则会发出警告

  • #8380: html 搜索: 搜索结果标签已损坏

  • #9198: i18n: Babel 在运行 compile_catalog 时发出错误

  • #9205: py 域: :canonical: 选项导致“交叉引用有多个目标”警告

  • #9201: websupport: 引发 UndefinedError: ‘css_tag’ 未定义

发布 4.0.0 (发布于 2021 年 5 月 9 日)

依赖项

4.0.0b1

  • 停止支持 Python 3.5

  • 停止支持 Docutils 0.12 和 0.13

  • LaTeX: 添加 tex-gyre 字体依赖

4.0.0b2

  • 支持 Docutils 0.17。请注意，它会改变 HTML 构建器的输出。某些主题不支持它，您需要更新自定义 CSS 以进行升级。

不兼容的更改

4.0.0b1

  • #8539: autodoc: 当 autodoc_typehints='description' 和 autoclass_content='class' 设置时，info-field-list 会生成到类描述中

  • #8898: extlinks: "%s" 在链接标题字符串中成为必需关键字

  • 域：Index 类现在是 abc.ABC 的子类，用于指示在具体类中必须重写的方法

  • #4826: py 域: Python 对象的结构已更改。添加了一个布尔值以指示 Python 对象是否是规范对象

  • #7425: MathJax: MathJax 从 2 更改为 3。使用自定义 MathJax 配置的用户可能需要设置旧的 MathJax 路径或更新其版本 3 的配置。请参阅 sphinx.ext.mathjax。

  • #7784: i18n: 图像的 alt 文本已更改

  • #5560: napoleon: napoleon_use_param 也影响“其他参数”部分

  • #7996: manpage: 默认情况下在构建手册页时创建节目录（参见 man_make_section_directory）

  • #7849: html: 将 html_codeblock_linenos_style 的默认设置更改为 'inline'

  • #8380: html 搜索: 搜索结果用 <p> 包装而不是 <div>

  • html 主题: 将 basic/layout.html 中用于 documentation_options.js 的脚本标签移动到 script_files 变量中

  • html 主题: 将 basic/layout.html 中的 CSS 标签移动到 css_files 变量中

  • #8915: html 主题: 对 sphinx_rtd_theme 0.2.4 或更早版本发出警告

  • #8508: LaTeX: uplatex 成为日语文档 latex_engine 的默认设置

  • #5977: py 域: :var:、:cvar: 和 :ivar: 字段不创建交叉引用

  • #4550: figure 和 table 节点的 align 属性默认为 None 而不是 'default'

  • #8769: LaTeX 重构: 将 sphinx.sty 拆分为多个文件，并重命名在 latex 构建输出目录中创建的一些辅助文件

  • #8937: 使用显式标题而不是 <无标题>

  • #8487: csv-table 指令的 :file: 选项现在将绝对路径识别为相对于源目录的相对路径

4.0.0b2

已弃用

  • html_代码块_行号_样式

  • HTML 模板中的 favicon 和 logo 变量

  • sphinx.directives.patches.CSVTable

  • sphinx.directives.patches.ListTable

  • sphinx.directives.patches.RSTTable

  • sphinx.ext.autodoc.directive.DocumenterBridge.filename_set

  • sphinx.ext.autodoc.directive.DocumenterBridge.warn()

  • sphinx.registry.SphinxComponentRegistry.get_source_input()

  • sphinx.registry.SphinxComponentRegistry.source_inputs

  • sphinx.transforms.FigureAligner

  • sphinx.util.pycompat.convert_with_2to3()

  • sphinx.util.pycompat.execfile_()

  • sphinx.util.smartypants

  • sphinx.util.typing.DirectiveOption

新增功能

4.0.0b1

  • #8924: autodoc: 支持 TypeVar 的 bound 参数

  • #7383: autodoc: 支持属性的类型提示

  • #5603: autodoc: 允许使用其规范名称引用 Python 类，当该类具有两个不同名称时：规范名称和别名

  • #8539: autodoc: 添加 autodoc_typehints_description_target 以控制 autodoc_typehints=description 的行为

  • #8841: autodoc: autodoc_docstring_signature 将继续查找不带反斜杠字符的多个签名行

  • #7549: autosummary: 默认启用 autosummary_generate

  • #8898: extlinks: 允许链接标题字符串中包含 %s

  • #4826: py 域: 为 python 指令添加 :canonical: 选项，以描述对象定义的位置

  • #7199: py 域: 添加 python_use_unqualified_type_names 以抑制可解析的 python 引用的模块名称（实验性）

  • #7068: py 域: 添加 py:property 指令以描述属性

  • #7784: i18n: 图像的 alt 文本默认翻译（不带 gettext_additional_targets 设置）

  • #2018: html: html_favicon 和 html_logo 现在接受图像的 URL

  • #8070: html 搜索: 支持搜索 2 个字符的单词

  • #9036: html 主题: 允许继承搜索页面

  • #8938: imgconverter: 显示命令可用性检查的错误

  • #7830: 添加源和模板更改检测的调试日志

  • #8201: 如果 toctree 包含重复条目，则发出警告

  • #8326: master_doc 现已重命名为 root_doc

  • #8942: C++，添加对 C++20 飞船操作符 <=> 的支持。

  • #7199: 新增节点 sphinx.addnodes.pending_xref_condition。它可用于根据条件选择适当的引用内容。

4.0.0b2

  • #8818: autodoc: 拥有 Any 参数的超类导致吹毛求疵的警告

  • #9095: autodoc: 在处理损坏的元类时引发 TypeError

  • #9110: autodoc: 在 py37+ 中，GenericAlias 的元数据未渲染为引用

  • #9098: html: Safari 中 doctests 的复制范围保护不起作用

  • #9103: LaTeX: imgconverter: 即使不需要，转换也会运行

  • #8127: py 域: info-field-list 中的省略号导致吹毛求疵的警告

  • #9121: py 域: 当文档中定义了规范对象及其别名对象时，会发出重复警告

  • #9023: 域描述上增加了更多的 CSS 类，详情请参阅 Sphinx 添加的 Doctree 节点类。

  • #8195: mathjax: 将 mathjax_config 重命名为 mathjax2_config 并添加 mathjax3_config

修复的 Bug

4.0.0b1

  • #8917: autodoc: 如果函数有错误的 __globals__ 值，则会引发警告

  • #8415: autodoc: 从其他模块导入的 TypeVar 未解析（在 Python 3.7 或更高版本中）

  • #8992: autodoc: 无法解析 types.TracebackType 类型注解

  • #8905: html: html_add_permalinks=None 和 html_add_permalinks="" 被忽略

  • #8380: html 搜索: 搜索结果中的段落未被识别为 <p>

  • #8915: html 主题: sphinx_rtd_theme 的翻译不起作用

  • #8342: 如果为指令或角色提供了未知域（例如 :unknown:doc:），则发出警告

  • #7241: LaTeX: cpp:enumerator 不换行

  • #8711: LaTeX: 代码块中的反引号在较新的 TeXLive 2019 中触发 latexpdf 构建警告（和字体更改）

  • #8253: LaTeX: 没有定义大小的图片被过度缩放（与明确以像素设置大小的图片相比）（仅针对 'pdflatex'/'lualatex' 修复）

  • #8881: LaTeX: PDF 中书签面板的深度不足以进行导航

  • #8874: LaTeX: 两个小 Pygments LaTeXFormatter 输出问题的修复忽略了 Pygments 样式

  • #8925: LaTeX: 3.5.0 verbatimmaxunderfull 设置未按预期工作

  • #8980: LaTeX: \pysigline 中缺少换行符

  • #8995: LaTeX: 传统的 \pysiglinewithargsret 未能正确计算可用水平空间，应使用不对齐的右边样式

  • #9009: LaTeX: 带有下划线的“release”值导致无效的 LaTeX

  • #8911: C++: 移除 cpp_index_common_prefix 中最长匹配的前缀，而不是第一个匹配的前缀。

  • C，在使用关键字作为参数名称时，正确拒绝函数声明。

  • #8933: viewcode: 在并行构建时无法创建反向链接

  • #8960: C 和 C++，修复函数参数列表中（成员）函数指针类型的渲染。

  • C++，修复数组声明符中、指向成员（函数）声明符中以及 sizeof... 参数中的名称链接。

  • C，修复数组声明符中名称的链接。

4.0.0b2

  • C, C++，修复当 alias 指令是文件中第一个 C/C++ 指令，并且后面还有另一个 C/C++ 指令时，出现的 KeyError。

4.0.0b3

  • #9167: html: 无法将 CSS 文件添加到特定页面