Sphinx 3.1

发布 3.1.2 (发布于 2020 年 7 月 5 日)

不兼容的变更

  • #7650: autodoc: 对于装饰函数，将显示基函数的签名，而不是装饰器的签名

修复的 Bug

  • #7844: autodoc: 给出相对模块名时未能检测到模块

  • #7856: autodoc: 将非类对象传递给 autoclass 指令时引发 AttributeError

  • #7850: autodoc: 当 autodoc_typehints 为 ‘description’ 时，对于无效标记会引发 KeyError

  • #7812: autodoc: 如果目标名称同时与同名的属性和模块匹配，则崩溃

  • #7650: autodoc: 如果函数由通用装饰器装饰，则函数签名变为 (*args, **kwargs)

  • #7812: autosummary: 如果目标代码包含同名的属性和模块，则生成损坏的存根文件

  • #7806: viewcode: 未能解决第三方构建器上的 viewcode 引用

  • #7838: html 主题: 列表项有额外的垂直空间

  • #7878: html 主题: “overflow” 和 “float” 之间存在不必要的交互

发布 3.1.1 (发布于 2020 年 6 月 14 日)

不兼容的更改

  • #7808: napoleon: 属性类型表示为类型化字段

新增功能

  • #7807: autodoc: 当 type_comment 与其签名不匹配时显示详细警告

修复的 Bug

  • #7808: autodoc: 变量和属性类型注解引发警告

  • #7802: autodoc: 在并行构建时引发 EOFError

  • #7821: autodoc: 对重载的 C 扩展函数引发 TypeError

  • #7805: autodoc: 描述符返回的对象被意外地记录

  • #7807: autodoc: 使用 contextmanager 的函数显示错误的签名

  • #7812: autosummary: 如果目标代码包含同名的属性和模块，则生成损坏的存根文件

  • #7808: napoleon: 变量和属性类型注解引发警告

  • #7811: sphinx.util.inspect 导致循环导入问题

发布 3.1.0 (发布于 2020 年 6 月 8 日)

依赖项

  • #7746: mathjax: 更新至 2.7.5

不兼容的更改

  • #7477: imgconverter: 在 Windows 上默认调用 “magick convert” 命令

已弃用

  • sphinx.ext.autosummary.generate.AutosummaryRenderer 的第一个参数已更改为 Sphinx 对象

  • sphinx.ext.autosummary.generate.AutosummaryRenderer 接受对象类型作为参数

  • sphinx.ext.autodoc.Documenter.get_doc() 的 ignore 参数

  • sphinx.ext.autosummary.generate. AutosummaryRenderer 的 template_dir 参数

  • sphinx.ext.autosummary.generate. find_autosummary_in_docstring() 的 module 参数

  • sphinx.ext.autosummary.generate. generate_autosummary_docs() 的 builder 参数

  • sphinx.ext.autosummary.generate. generate_autosummary_docs() 的 template_dir 参数

  • sphinx.util.docstring.prepare_docstring() 的 ignore 参数

  • sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()

  • sphinx.util.rpartition()

新增功能

  • LaTeX: 在 LaTeX 主题中使 toplevel_sectioning 设置可选

  • LaTeX: 允许从 LaTeX 主题覆盖纸张大小和字号

  • LaTeX: 添加 latex_theme_options 以覆盖主题选项

  • #7410: 允许使用 suppress_warnings 抑制“检测到循环 toctree 引用”警告

  • C，添加了作用域控制指令：c:namespace、c:namespace-push 和 c:namespace-pop。

  • #2044: autodoc: 抑制实例属性的默认值

  • #7473: autodoc: 如果 docstring 在 info-field-list 中包含 :meta public:，则认为成员是公共的

  • #7487: autodoc: 允许通过 py:autofunction 为 singledispatch 函数生成文档

  • #7143: autodoc: 支持 final 类和方法

  • #7384: autodoc: 支持由 __new__()、元类和内置基类定义的签名

  • #2106: autodoc: 支持 docstring 上的多个签名

  • #4422: autodoc: 支持 Python 3.7 或更高版本中的 GenericAlias

  • #3610: autodoc: 支持重载函数

  • #7722: autodoc: 支持 TypeVar

  • #7466: autosummary: 生成文档中的标题未翻译

  • #7490: autosummary: 为 autosummary 指令添加 :caption: 选项以设置 toctree 的标题

  • #7469: autosummary: 支持模块属性

  • #248, #6040: autosummary: 为 autosummary 指令添加 :recursive: 选项以递归生成存根文件

  • #4030: autosummary: 添加 autosummary_context 以添加自定义模板的模板变量

  • #7530: html: 支持嵌套的 <kbd> 元素

  • #7481: html 主题: 为脚注/引用标签添加右边距

  • #7482, #7717: html 主题: 带标题和行号的代码块的 CSS 间距

  • #7443: html 主题: 添加新选项 globaltoc_collapse 和 globaltoc_includehidden 以控制侧边栏中 globaltoc 的行为

  • #7484: html 主题: 避免侧边栏与其他块之间的冲突

  • #7476: html 主题: Relbar 面包屑应包含当前页面

  • #7506: html 主题: 规范 URL 未转义

  • #7533: html 主题: 避免 genindex.html 开头的空白

  • #7541: html 主题: 在“body”末尾添加一个“clearer”

  • #7542: html 主题: 使 admonition/topic/sidebar 可滚动

  • #7543: html 主题: 为表格添加上下边距

  • #7695: html 主题: 为基本主题添加 viewport meta 标签

  • #7721: html 主题: classic: 默认的 codetextcolor/codebgcolor 不覆盖 Pygments

  • C 和 C++: 允许声明末尾有分号。

  • C++: 解析参数化 noexcept 声明符。

  • #7294: C++: 解析带有用户定义字面量的表达式。

  • C++: 解析尾随返回类型。

  • #7143: py domain: 为 py:class、py:exception 和 py:method 指令添加 :final: 选项

  • #7596: py domain: 将变量的类型注解更改为超链接

  • #7770: std domain: option 指令支持 foo[=bar] 形式的参数

  • #7582: napoleon: 属性类型表示为类型注解

  • #7734: napoleon: 属性上尾随下划线过度转义

  • #7247: linkcheck: 添加 linkcheck_request_headers 以向特定主机发送自定义 HTTP 头

  • #7792: setuptools: 支持 --verbosity 选项

  • #7683: 为 Sphinx.emit() 添加 allowed_exceptions 参数以允许处理程序引发指定的异常

  • #7295: C++: 解析（尾随）requires 子句。

修复的 Bug

  • #6703: autodoc: 增量构建对导入对象不起作用

  • #7564: autodoc: 描述符不显示注解

  • #6588: autodoc: 装饰的继承方法没有文档

  • #7469: autodoc: 变量的 autodoc-process-docstring 更改被意外缓存

  • #7559: autodoc: 错误地将同步函数检测为异步函数

  • #6857: autodoc: 未能检测到 Enum 类上的 classmethod

  • #7562: autodoc: 在 autodoc_typehints='description' 模式下，包含空格的类型提示渲染错误

  • #7551: autodoc: 未能导入嵌套类

  • #7362: autodoc: 未能为内置函数渲染正确的签名

  • #7654: autodoc: Optional[Union[foo, bar]] 显示为 Union[foo, bar, None]

  • #7629: autodoc: 如果指定了无效对象，autofunction 会发出不友好的警告

  • #7650: autodoc: 对于装饰函数显示未装饰的签名

  • #7676: autodoc: autodoc_member_order 默认值中的拼写错误

  • #7676: autodoc: :member-order: 选项的错误值被静默忽略

  • #7676: autodoc: member-order=”bysource” 对 C 模块不起作用

  • #3673: autodoc: member-order=”bysource” 对具有 __all__ 的模块不起作用

  • #7668: autodoc: 错误的 retann 值传递给 autodoc-process-signature 的处理程序

  • #7711: autodoc: 处理 numpy 对象时因 ValueError 失败

  • #7791: autodoc: 记录 singledispatch 函数时引发 TypeError

  • #7551: autosummary: 嵌套类被索引为非嵌套类

  • #7661: autosummary: 如果导入目标模块失败，autosummary 指令会发出两次警告

  • #7685: autosummary: 即使 autossummary_imported_members 为 False，模板变量“members”也包含导入成员

  • #7671: autosummary: 缺少导入失败警告的位置

  • #7535: sphinx-autogen: 当自定义模板使用继承时崩溃

  • #7536: sphinx-autogen: 当模板使用 i18n 功能时崩溃

  • #7781: sphinx-build: 当 outdir 不是目录时显示错误的错误消息

  • #7653: sphinx-quickstart: 修复嵌套相对路径的多个目录创建

  • #2785: html: 方程式链接对齐不良

  • #7718: html 主题: 某些主题不尊重 Pygments 样式的背景颜色（agogo, haiku, nature, pyramid, scrolls, sphinxdoc 和 traditional）

  • #7544: html 主题: admonitions 中的填充不一致

  • #7581: napoleon: 属性 docstring 中的内联代码解析不良

  • #7628: imgconverter: 对于不支持图像的构建器，不必要地运行 imagemagick 一次

  • #7610: 对于 Docutils 0.16 错误地渲染连续的反斜杠

  • #7646: 处理事件处理程序中的错误

  • #4187: LaTeX: 日语文档中 PDF 书签中的 EN DASH 消失

  • #7701: LaTeX: 匿名间接超链接目标导致重复标签

  • #7723: LaTeX: 当 URL 包含单引号时 pdflatex 崩溃

  • #7756: py domain: 未显示仅位置参数的默认值

  • #7760: coverage: 添加 coverage_show_missing_items 以向控制台显示覆盖结果

  • C++: 修复在全局作用域中显式开始的嵌套名称（例如 ::A::B）的渲染和交叉引用。

  • C: 修复在全局作用域中显式开始的嵌套名称（例如 .A.B）的渲染和交叉引用。

  • #7763: C 和 C++: 在一元表达式和折叠表达式的显示字符串化期间不会崩溃。