Sphinx 1.7¶

发布 1.7.9（发布于 2018 年 9 月 5 日）¶

新增功能¶

#5359：通过排序锚点使生成的 texinfo 文件可重现

修复的 Bug¶

#5361：如果文档使用 include 指令，则增量构建崩溃

发布 1.7.8（发布于 2018 年 8 月 29 日）¶

不兼容的变更¶

env.included 的类型已更改为 dict of set

修复的 Bug¶

#5320：intersphinx：如果给定无效 URL 则崩溃
#5326：manpage：当指定无效 docname 作为 man_pages 时崩溃
#5322：autodoc：Any 类型提示导致格式错误
#5327：重新构建生成的文件时出现“文档未包含在任何 toctree 中”警告
#5335：quickstart：MacPorts 的 python 显示了转义序列

发布 1.7.7（发布于 2018 年 8 月 19 日）¶

修复的 Bug¶

#5198：仅用于并行构建时包含文件时出现“文档未在 toctree 中”警告
LaTeX：减少 latex 控制台输出中的“Token not allowed in a PDF string”hyperref 警告（参考：#5236）
LaTeX：使用最新的 LaTeX 时，在 latex 控制台输出中抑制“remreset Warning: The remreset package is obsolete”（参考：#5237）
#5234：PDF 输出：自 Sphinx 1.5 以来，PAPER 环境变量的使用已损坏
LaTeX：修复 latex_engine 关于带有 XeLaTeX/LuaLateX 的 Latin Modern 字体的文档（参考：#5251）
#5280：autodoc：修复复杂类型化的错误类型注释
autodoc：可选类型渲染错误
#5291：autodoc 因 ForwardRef 类型而崩溃
#5211：autodoc：未为 functools.partial 函数生成文档
#5306：autodoc：getargspec() 为无效类型提示引发 NameError
#5298：imgmath：math_number_all 导致 html 中的公式有两个数字
#5294：sphinx-quickstart 在 PowerShell 中出现空白提示

发布 1.7.6（发布于 2018 年 7 月 17 日）¶

修复的 Bug¶

#5037：LaTeX \sphinxupquote{} 在俄语中中断
sphinx.testing 使用已弃用的 pytest API；Node.get_marker(name)
#5016：启用 recommonmark.AutoStrictify 时崩溃
#5022：latex：因 Debian/Ubuntu 提供的 Docutils 包而崩溃
#5009：latex：如果表格没有标题，则表格的标签会消失
#5048：带编号的 toctree 崩溃
#2410：C，为宏渲染空参数列表。
C++，修复没有模板参数的完整模板特化查找。
#4667：C++，修复使用 intersphinx 时全局作用域中缺少引用的断言。感谢 Alan M. Carroll。
#5019：autodoc：因换页符而崩溃
#5032：autodoc：丢失旧式类的第一个 staticmethod 参数
#5036：quickstart：键入 Ctrl-U 清除整行
#5066：html：“relations”侧边栏默认不显示
#5091：latex：索引条目中的花括号处理不正确
#5070：epub：内部 href 片段链接错误
#5104：apidoc：sphinx.apidoc:main() 的接口已更改
#4272：法语项目的 PDF 构建在 XeTeX 中存在问题
#5076：napoleon 在 python 3.7 中引发 RuntimeError
#5125：sphinx-build：sphinx:main() 的接口已更改
sphinx-build：sphinx.cmd.build.main() 引用 sys.argv 而不是给定参数
#5146：autosummary：当 docstring 的第一行以文字表示结束时，会发出警告
autosummary：autosummary 的警告指示错误位置（参考：#5146）
#5143：autodoc：在检查不支持排序的类似 dict 对象时崩溃
#5139：autodoc：如果 Enum 参数与其他参数共享值，则缺失
#4946：py domain：rtype 字段无法将“None”作为类型处理
#5176：LaTeX：包含 @、! 或 " 的术语索引失败
#5161：html：如果复制静态文件失败则崩溃
#5167：autodoc：修复具有两个以上参数的元组的格式类型注释
#3329：i18n：因自动符号脚注引用而崩溃
#5158：autosummary：模块摘要在以标题开头时已损坏

发布 1.7.5（发布于 2018 年 5 月 29 日）¶

修复的 Bug¶

#4924：html 搜索：其他语言中的大写字符问题
#4932：apidoc：如果同级子包包含以下划线开头的模块，则某些子包被忽略
#4863、#4938、#4939：i18n 未正确处理用于内容、主题、警告、表格和节的 node.title。
#4913：i18n：项目符号列表中的文字块未翻译
#4962：C++，在重复声明时引发 TypeError。
#4825：C++，正确解析 expr 角色，并在存在（转义的）换行符时提供更好的错误消息。
C++，正确使用 desc_addname 节点作为名称前缀。
C++，解析函数调用中的包扩展。
#4915、#4916：使用 dirhtml 构建器时搜索页面上的链接损坏
#4969：autodoc：构造函数方法不应有返回注释
latex：以非 1 开头的深层嵌套枚举列表导致 LaTeX 引擎崩溃
#4978：latex：未为巴西区域设置 shorthandoff
#4928：i18n：忽略 LC_MESSAGES/ 中的点目录，例如 .git/
#4946：py domain：类型字段无法将“None”作为类型处理
#4979：latex：索引条目中的花括号转义不正确
#4956：autodoc：未能从模拟模块上的类的子类中提取文档
#4973：latex：glossary 指令为每个项目添加空格
#4980：latex：代码块上的显式标签重复
#4919：如果 toctree 有 :numbered: 选项，则 node.asdom() 崩溃
#4914：autodoc：使用没有默认值的 dataclasses 时解析错误
#4931：autodoc：当 autodoc-skip-member 的处理程序引发错误时崩溃
#4931：autodoc：当模拟类的子类由 napoleon 模块处理时崩溃
#5007：当错误日志包含“%”字符时，sphinx-build 崩溃

发布 1.7.4（发布于 2018 年 4 月 25 日）¶

修复的 Bug¶

#4885、#4887：domains：因重复对象而崩溃
#4889：latex：sphinx.writers.latex 导致递归导入

发布 1.7.3（发布于 2018 年 4 月 23 日）¶

修复的 Bug¶

#4769：autodoc 丢失第一个 staticmethod 参数
#4790：autosummary：PDF 构建中过宽的两列表格
#4795：通过 _templates/longtable.tex_t 进行的 Latex 自定义已损坏
#4789：imgconverter：被 Windows 的 convert.exe 混淆
#4783：在 windows 上，当 srcdir 和 outdir 的驱动器不同时，Sphinx 崩溃
#4812：autodoc 忽略类型注释变量
#4817：警告消息中的 URL 错误
#4784：latex：如果替换中存在超链接，latex_show_urls 分配不正确的脚注编号
#4837：带 memoir 类的 latex 错误：不支持字体命令 \sf
#4803：latex：与自动编号脚注数量成比例过慢
#4838：htmlhelp：.hhp 文件中的条目未排序
toctree 指令尝试全局匹配具有 query_string 的 URL
#4871：html 搜索：德语中的大写字符问题
#4717：latex：LuaLaTeX 和 XeLaTeX 的德语文档编译失败
#4459：重复标签检测器在并行构建中效果不佳
#4878：因返回无效元数据的扩展而崩溃

发布 1.7.2（发布于 2018 年 3 月 21 日）¶

不兼容更改¶

#4520：apidoc：空 __init__.py 的文件夹不再从 TOC 中排除

已修复的错误¶

#4669：sphinx.build_main 和 sphinx.make_main 抛出 NameError
#4685：autosummary 发出无意义的警告
autodoc：给定无效选项时崩溃
pydomain：如果为空则始终去除括号（参考：#1042）
#4689：autosummary：意外地去除包含“i.e.”的 docstring
#4701：viewcode：viewcode html 输出中 <div> 位置错误
#4444：不需要 numfig 才能在节上使用 :numref:
#4727：包 textcomp 的选项冲突
#4725：Sphinx 不适用于 python 3.5.0 和 3.5.1
#4716：在 Windows 上使用 TexLive 生成 PDF 文件，文件未找到错误
#4574：latex 中公式前的垂直空格
#4720：当图像与构建器不匹配时，消息不明确
#4655、#4684：波兰语和中文中的不完整本地化字符串
#2286：在渲染 HTML 页面时发生错误时 Sphinx 崩溃
#4688：下载具有长 URL 的远程图像时出错
#4754：sphinx/pycode/__init__.py 引发 AttributeError
#1435：qthelp 构建器应进行 htmlescape 关键字
epub：修复 toc.ncx 的 docTitle 元素未转义
#4520：apidoc：toc 中没有子包（1.6.6 中引入）现已修复
#4767：html：搜索高亮破坏了 mathjax 公式

发布 1.7.1（发布于 2018 年 2 月 23 日）¶

已弃用¶

#4623：sphinx.build_main() 已弃用。
autosummary：sphinx.ext.autosummary.get_documenter() 的接口已更改（自 1.7.0 起）
#4664：sphinx.ext.intersphinx.debug() 已弃用。

有关更多详细信息，请参阅已弃用 API 列表。

已修复的错误¶

#4608：epub：生成无效元标签
#4260：autodoc：如果关键字参数分隔符出现在参数列表的顶部，则不会消失
#4622：epub：epub_scheme 不影响 content.opf
#4627：graphviz：调整 graphviz 图像以适应页面
#4617：quickstart：PROJECT_DIR 参数是必需的
#4623：sphinx.build_main 在 1.7.0 中不再存在
#4615：sphinx.build 的参数在 1.7.0 中已更改
autosummary：sphinx.ext.autosummary.get_documenter() 的接口已更改
#4630：使 sphinx.pot 中的 msgid 有确定顺序
#4563：autosummary：不正确的行尾标点检测
#4577：显式开始的枚举子列表编号错误
#4641：TOC 中的外部链接不能包含带 :glob: 选项的“?”
C++，添加对表达式解析中显式类型转换和 typeid 的缺失解析。
C++，添加对表达式解析中 this 的缺失解析。
#4655：修复波兰语中不完整的本地化字符串
#4653：修复无参数 ImportError 的错误报告
#4664：读取 objects.inv 再次失败
#4662：遇到歧义时，带 term 目标的 any 引用崩溃

发布 1.7.0（发布于 2018 年 2 月 12 日）¶

依赖项¶

1.7.0b1

添加 packaging 包

不兼容更改¶

1.7.0b1

#3668：每个命令的主函数的参数已更改
#3893：未知 html_theme_options 会引发警告而不是错误
#3927：Python 参数/变量类型应与类匹配，而不是所有对象
#3962：sphinx-apidoc 现在在给定 --implicit-namespaces 选项时将给定目录识别为隐式命名空间包，而不是给定目录的子目录。
#3929：apidoc：将 sphinx.apidoc 移动到 sphinx.ext.apidoc
#4226：apidoc：生成新样式 makefile（make-mode）
#4274：sphinx-build 在参数错误时返回 2 作为退出代码
#4389：输出目录将在加载扩展后创建
autodoc 不会向生成的文档生成警告消息，即使 keep_warnings 为 True。它们仅发送到 stderr。
shebang 行已从生成的 conf.py 中删除
#2557：autodoc：autodoc_mock_imports 仅模拟指定的模块及其后代。它不模拟它们的祖先。如果您想模拟它们，请显式指定祖先的名称。
#3620：html 主题：将 DOCUMENTATION_OPTIONS 移动到独立的 JavaScript 文件（参考：#4295）
#4246：限制所有主题的文本正文宽度。可通过主题选项 body_min_width 和 body_max_width 进行配置。
#4771：apidoc：如果 exclude_patterns 参数紧跟在命令行选项之后，则它们将被忽略

1.7.0b2

#4467：html 主题：将 csss 块重命名为 css

已弃用¶

1.7.0b1

将字符串值用于 html_sidebars 已弃用，2.0 版将只接受列表值。
format_annotation() 和 formatargspec() 已弃用。请改用 sphinx.util.inspect.Signature。
sphinx.ext.autodoc.AutodocReporter 已被 sphinx.util.docutils. switch_source_input() 替换，现已弃用。它将在 Sphinx 2.0 中删除。
sphinx.ext.autodoc.add_documenter() 和 AutoDirective._register 现已弃用。请改用 app.add_autodocumenter()。
AutoDirective._special_attrgetters 现已弃用。请改用 app.add_autodoc_attrgetter()。

新增功能¶

1.7.0b1

C++，处理 decltype(auto)。
#2406：C++，添加表达式的正确解析，包括标识符的链接。
C++，添加 cpp:expr 角色，用于插入内联 C++ 表达式或类型。
C++，支持带有速记 template 前缀的显式成员实例化
C++，使函数参数可链接，如模板参数。
#3638：允许使用 math_eqref_format 更改对公式引用的标签
现在 suppress_warnings 接受以下配置
- ref.python (ref: #3866)
#3872：添加 latex 键以配置 PDF 输出中文字块标题位置（参考 #3792, #1723）
如果缺少 docstring，尝试从基类中检索 doc（参考：#3140）
#4023：澄清当任何角色有多个目标时的错误消息。
#3973：epub：允许覆盖构建日期
#3972：epub：按文件名排序清单条目
#4052：viewcode：在突出显示模块代码之前排序
#1448：qthelp：添加新的配置值；qthelp_namespace
#4140：html 主题：使 body 标签可继承
#4168：使用 jieba 改进中文搜索
HTML 主题可以通过 theme.conf 设置默认侧边栏
#3160：html：使用 <kdb> 表示 :kbd: 角色
#4212：autosummary：导入模块时捕获所有异常
#4166：添加 math_numfig 用于按节编号公式（参考：#3991，#4080）。感谢 Oliver Jahn。
#4311：让 LaTeX 遵守 numfig_secnum_depth 用于图、表和代码块
#947：autodoc 现在支持 ignore-module-all 以忽略模块的 __all__
#4332：让 LaTeX 遵守 math_numfig 用于公式编号
#4093：sphinx-build 为未知目标/构建器创建空目录
为 sphinx.ext.inheritance_diagram 扩展添加 top-classes 选项，以限制继承图的范围。
#4183：doctest：:pyversion: 选项也遵循 PEP-440 规范
#4235：html：添加 manpages_url 以将 manpage 角色转换为超链接
#3570：autodoc：不显示用于类型提示的“typing.”模块
#4354：sphinx-build 现在发出完成消息。构建器可以通过 Builder.epilog 属性修改它
#4245：html 主题：将 language 添加到 javascript 变量列表
#4079：html：为每个代码块、文字和数学添加 notranslate 类，以让 Google 翻译知道它们不可翻译
#4137：doctest：doctest 块总是突出显示为 python 控制台（pycon）
#4137：doctest：testcode 块总是突出显示为 python
#3998：text：默认分配节编号。您可以使用 text_add_secnumbers 和 text_secnumber_suffix 控制它

1.7.0b2

#4271：sphinx-build 支持一个名为 -j auto 的选项，以自动调整进程数量。
Napoleon：添加了指定自定义节标签的选项。

已移除的功能¶

1.7.0b1

配置变量
- html_use_smartypants
- latex_keep_old_macro_names
- latex_elements['footer']
sphinx.application.Sphinx 类的实用方法
- buildername（属性）
- _display_chunk()
- old_status_iterator()
- status_iterator()
- _directive_helper()
sphinx.environment.BuildEnvironment 类的实用方法
- currmodule（属性）
- currclass（属性）
epub2 构建器
warn() 的 prefix 和 colorfunc 参数
sphinx.util.compat 模块
sphinx.util.nodes.process_only_nodes()
LaTeX 环境 notice，请改用 sphinxadmonition
LaTeX \sphinxstylethead，请改用 \sphinxstyletheadfamily
C++，支持函数概念。感谢 mickk-on-cpp。
未使用的且之前未文档化的 LaTeX 宏 \shortversion 和 \setshortversion

已修复的错误¶

1.7.0b1

#3882：更新 HTMLHelp 和 QTHelp 的文件顺序
#3962：sphinx-apidoc 未能正确识别隐式命名空间包
#4094：C++，允许空模板参数列表。
C++，也在具有限定名称的声明名称中超链接类型。
C++，不为概念内的声明添加索引条目。
C++，支持依赖名称的模板消歧符。
#4314：对于 PDF ‘howto’ 文档，代码块的编号与图和表的编号不同
#4330：PDF ‘howto’ 文档具有不一致的默认 LaTeX tocdepth 计数器设置
#4198：autosummary 发出多个“autodoc-process-docstring”事件。感谢 Joel Nothman。
#4081：构建时警告和错误颜色相同
latex：如果未设置 release，则不显示“Release”标签

1.7.0b2

#4415：autodoc 将继承的类方法归类为常规方法
#4415：autodoc 将继承的静态方法归类为常规方法
#4472：DOCUMENTATION_OPTIONS 未定义
#4491：autodoc：优先选择 _MockImporter 而不是 sys.meta_path 中的其他导入器
#4490：autodoc：python 3.7.0a4+ 的类型注释损坏
utils 包不再安装
#3952：apidoc：模块头被过度转义
#4275：sphinx.util.i18n.format_date 接受的格式受到限制
#4493：如果启用 AutoStructify，recommonmark 会引发 AttributeError
#4209：intersphinx：在链接标题中，如果目标没有版本，“v”应该是可选的
#4230：Sphinx 1.6 写入页面速度变慢
#4522：epub：即使配置更改，文档也不会重建

1.7.0b3

#4019：inheritance_diagram AttributeError 停止构建过程
#4531：autosummary：方法不被视为属性
#4538：autodoc：sphinx.ext.autodoc.Options 已移动
#4539：autodoc 为 partialmethods 发出警告
#4223：doctest：在错误文件和错误行报告失败的测试
i18n：如果为 sphinx-build 作为参数提供了特定的文件名，则消息目录不会编译（参考：#4560）
#4027：sphinx.ext.autosectionlabel 现在期望标签与原始源中的标签相同；没有智能引号，没有花哨的东西。
#4581：apidoc：排除的模块仍包含在内

测试¶

1.7.0b1

添加对 Docutils 0.14 的支持
为 sphinx.ext.inheritance_diagram 扩展添加测试。