Sphinx 3.1

Release 3.1.2（Jul 05, 2020 发布）

不兼容的变更

  • #7650：autodoc：对于修饰函数，将显示基函数的签名，而非 decorator 的签名

Bug 修复

  • #7844：autodoc：在给定相对模块名称时无法检测模块

  • #7856：autodoc：将 non-class 对象提供给 autoclass 指令时引发 AttributeError

  • #7850：autodoc：当 autodoc_typehints 为 'description' 时为无效标记时会引发 KeyError

  • #7812：autodoc：将被损毁如果目标名称与同名的属性和模块都匹配

  • #7650：autodoc：如果函数由泛型装饰器修饰，则函数签名将变为 (*args, **kwargs)

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

  • #7806:：viewcode：无法解析第三方生成器上的 viewcode 引用

  • #7838：html theme：列表项有额外的垂直空间

  • #7878：html theme："overflow" 和 "float" 相互影响

Release 3.1.1 （Jun 14, 2020 发布）

不兼容的变更

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

新增特性

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

Bug 修复

  • #7808：autodoc：在变量和属性类型批注上引发警告

  • #7802：autodoc：在并行建构是引发 EOFError

  • #7821：autodoc：在负载 C-ext 函数是引发 TypeError

  • #7805：autodoc：描述符返回的对象被偶然的记录下来

  • #7807：autodoc：函数使用 contextmanager 时会出现错误的签名

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

  • #7808：napoleon：在变量和属性类型批注上引发警告

  • #7811：sphinx.util.inspect 引发循环导入错误

Release 3.1.0 （发布于Jun 08, 2020）

依赖

  • #7746：mathjax：更新至 2.7.5

不兼容的变更

  • #7477：imgconverter：在 Windows 上默认引发 "magick convert"

已弃用

  • The first argument for sphinx.ext.autosummary.generate.AutosummaryRenderer has been changed to Sphinx object

  • 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

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

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

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

  • sphinx.util.rpartition()

新增特性

  • LaTeX：让 toplevel_sectioning 在 LaTeX 主题中可选

  • LaTeX：允许重写 LaTeX 主题的 papersize 和 pointsize

  • LaTeX：增加 latex_theme_options 以推翻主题选项

  • #7410：允许在 suppress_warnings 时禁用 "circular toctree references detected"

  • C，增加了范围控制指令 c:namespace， c:namespace-push，和 c:namespace-pop。

  • #2044：autodoc：禁用实例属性的默认值

  • #7473：autodoc：如果字符串 info-field-list 中含 :meta public: in info-field-list 则考虑公共成员

  • #7487：autodoc：允许按 py:autofunction 为单次调度函数生成单据

  • #7143：autodoc：支持最终的类和方法

  • #7384：autodoc：支持由 __new__()，metaclasses 和 builtin 基类定义的签名

  • #2106：autodoc：支持字符串的额多个签名

  • #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 theme：在脚注/引文标签上添加右边距

  • #7482，#7717：html theme：带有标题和行号的代码块的 CSS 间距

  • #7443：html theme：给 globaltoc_collapse 和 globaltoc_includehidden 以控制侧边栏 globaltoc 的表现

  • #7484：html theme：避免边栏和其他块之间的冲突

  • #7476：html theme：Relbar breadcrumb 应该包含当前页面

  • #7506：html theme：规范 URL 未转义

  • #7533：html theme：避免 genindex.html 开头的空白

  • #7541：html theme：给 "body" 的末尾加 "clearer"

  • #7542：html theme：使警告/主题/侧栏可滚动

  • #7543：html theme：给表格加上下边距

  • #7695：html theme：为基本主题添加 viewport meta 标记

  • #7721：html theme：classic：默认 codetextcolor/codebgcolor 不覆盖 Pygments

  • C and C++：允许在声明末尾使用分号。

  • C++，解析参数化的 noexcept 说明符。

  • #7294：C++，使用用户定义的常量解析表达式。

  • C++，解析尾部返回类型。

  • #7143: py domain: Add :final: option to py:class, py:exception and py:method directives

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

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

  • #7582：napoleon：属性的类型表示为类型注释

  • #7734：napoleon：属性的尾缀下划线覆盖

  • #7247：linkcheck：在给特定主机的发送 HTTP 头时增加 linkcheck_request_headers

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

  • #7683：将 allowed_exceptions 参数增加到 Sphinx.emit() 中以允许处理器触发特定的异常

  • #7295：C++，解析（尾部）返回类型。

Bug 修复

  • #6703：autodoc：增量生成不适用于导入的对象

  • #7564：autodoc：说明不显示描述符的说明

  • #6588：autodoc：修饰继承方法没有文档

  • #7469：autodoc：意外缓存了变量的 utodoc-process-docstring 的更改

  • #7559：autodoc：误检测到同步功能是异步的

  • #6857：autodoc：在枚举类上检测不到 classmethod

  • #7562: autodoc: a typehint contains spaces is wrongly rendered under autodoc_typehints='description' mode

  • #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" does not work for a module having __all__

  • #7668: autodoc: wrong retann value is passed to a handler of autodoc-process-signature

  • #7711：autodoc：处理 numpy 对象时失败，出现 ValueError 报错

  • #7791：autodoc：在记录 singledispatch 函数时出现 TypeError

  • #7551：autosummary：一个嵌套类被按照非嵌套类编制了索引

  • #7661：autosummary：如果导入目标模块失败，autosummary 指令将发出警告

  • #7685: autosummary: The template variable "members" contains imported members even if autossummary_imported_members is False

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

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

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

  • #7781：sphinx-build：当 outdir 不是目录时会报错

  • #7653：sphinx-quickstart：修复嵌套 relpath 创建多个目录的功能

  • #2785：html：公式链接对齐错误

  • #7718：html theme：有些主题不支持 Pygments 风格的背景色（agogo，haiku，nature，pyramid，scrolls，sphinxdoc 和 traditional）

  • #7544：html theme：警告中的 padding 前后矛盾

  • #7581：napoleon：属性 docstrings 中的内联代码分析错误

  • #7628：imgconverter：运行 imagemagick 一次对于不支持映像的构建程序是不必要的

  • #7610: incorrectly renders consecutive backslashes for 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++，在显示一元表达式和折叠表达式时不会崩溃。