Sphinx 1.6

发布 1.6.7（发布日期:2018年2月4日）

修复的错误

  • #1922: html 搜索: 法语中的大写字母问题

  • #4412: 将jQuery版本从3.1.0更新到3.2.1

  • #4438: 数学:带空格的带标签数学会导致 HTML 错误

  • #2437: 为类生成完整引用,别名为 “alias of”

  • #4434: 纯数字作为链接目标会产生警告

  • #4477: 构建在构建特定文件后失败

  • #4449: apidoc: 包含包含模块的 “空” 包

  • #3917: 引用标签被转换为省略号

  • #4501: graphviz: 如果图形不可点击,导致 epub3 验证错误

  • #4514: graphviz: 针对graphviz生成错误地图ID的解决方法

  • #4525: autosectionlabel 不支持并行构建

  • #3953: 当存在有效的 intersphinx 目录时,不要引发警告

  • #4487: 数学: 在并行构建时引发ValueError.感谢jschueller.

  • #2372: autosummary: 类型注解函数的无效签名被显示

  • #3942: html: 表格没有居中对齐,即使 :align: center

发布 1.6.6 （发布于 2018 年 1 月 08 日）

添加的特性

  • #4181: autodoc: 在可能的情况下对字典键进行排序

  • VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)

  • 更容易自定义与代码块渲染相关的LaTeX宏

  • 如果conf.py引发异常,则显示回溯（参考:#4369）

  • 在 conf.py 中添加 smartquotes 以禁用智能引号（参考:#3967）

  • 添加 smartquotes_action 和 smartquotes_excludes (参考:#4142, #4357)

修复的错误

  • #4334: sphinx-apidoc: 不在目录中生成对不存在文件的引用

  • #4206:latex:reST标签在段落之间丢失段落分隔

  • #4231: html: 仅在Firefox下应用fixFirefoxAnchorBug

  • #4221: napoleon 依赖 autodoc,但用户需要手动加载它

  • #2298: automodule无法记录类属性

  • #4099: C++: 正确地将构造函数内部的类引用链接到类

  • #4267: PDF 构建因 Unicode U+2116 数字符号字符而损坏

  • #4249: PDF 输出:Pygments 错误高亮导致代码块行间距增加

  • #1238: 支持 :emphasize-lines: 在 PDF 输出中

  • #4279: Sphinx在使用多个进程和远程图像时,因序列化错误崩溃

  • #1421: 尊重 sphinx-quickstart 中的安静标志

  • #4281: 创建输出目录时的竞争条件

  • #4315: 对于 PDF ‘howto’ 文档, latex_toplevel_sectioning='part' 生成 \chapter 命令

  • #4214: 两个待办事项指令破坏 Sphinx 1.6.5

  • 修复外部选项文档的链接,使用intersphinx（参考:#3769）

  • #4091: 未使用 :undoc-members: 的私有成员未被文档化:

版本 1.6.5（发布于 2017 年 10 月 23 日）

添加的特性

  • #4107: 使searchtools.js与pre-Sphinx1.5模板兼容

  • #4112: 如果已经设置了smart_quotes选项,请勿覆盖该设置

  • #4125: 在国际化警告信息中显示原文和翻译段落的参考文本

  • #4147: 在记录PO/MO文件的读/写时包含异常

修复的错误

  • #4085: 使用 :align: 选项时,解析文字中的图像生成 PDF 失败

  • #4100: 从autodoc扩展中移除调试打印

  • #3987: 将主题从 alabaster 更改会导致 HTML 构建失败

  • #4096: C++,使用错误的角色类型时不崩溃.感谢 mitya57.

  • #4070, #4111: 当警告信息包含格式字符串时崩溃（再次）

  • #4108: 搜索词高亮破坏 SVG 图像

  • #3692: 如果写入.buildinfo失败,则无法构建HTML

  • #4152: 如果字段列表放置在文档顶部,HTML写入器会崩溃

  • #4063 : 当标记指令 .. todolist:: 时,Sphinx 崩溃

  • #4134: [文档] docutils.conf 未明确记录

  • #4169: 中文不自动触发中文搜索

  • #1020: ext.todo 待办事项列表未链接到pdflatex中的页面

  • #3965: 新的快速入门在Makefile中生成错误的SPHINXBUILD

  • #3739::module: 选项在 pyobjects 内容中被忽略

  • #4149: 文档: 帮助选择 latex_engine

  • #4090: [文档] latex_additional_files 具有额外 LaTeX 宏时不应使用 .tex 扩展名

  • 无法将reST解析器错误转换为警告（参考文献:#4132）

发布版本 1.6.4（发布于2017年9月26日）

添加的特性

  • #3926: 添加 autodoc_warningiserror 以抑制在导入目标模块时 -W 选项的行为

修复的错误

  • #3924: 扩展中动态解析RST后文档名丢失

  • #3946:sphinx.sty中的拼写错误（这在默认上下文中是一个没有影响的bug）

  • pep:

    并且 :rfc: 不支持 default-role 指令（参考:#3960）

  • #3960: default_role = ‘guilabel’ 无法正常工作

  • 缺少 texinputs_win/Makefile 以用于 Windows 上的 latexpdf 构建器.

  • #4026: 自然: 修复macOS Safari滚动条颜色

  • #3877: 修复C++多行签名.

  • #4006: 修复并行构建时崩溃

  • #3969: 私有实例属性导致 AttributeError

  • #4041: C++,在函数指针中移除多余的名称链接.

  • #4038: C,添加缺失的 member 角色文档.

  • #4044: 空的多列单元格导致PDF输出中的额外行高

  • #4049: 修复sphinx-build -h输出中的拼写错误

  • #4062:在Python 3中,hashlib.sha1()必须接受字节,而不是unicode

  • 避免在 LaTeX 中索引条目后缩进（参考:#4066）

  • #4070: 当警告信息包含格式字符串时崩溃

  • #4067: 当make子进程失败时返回非零退出状态

  • #4055: graphviz: :align: 选项在 SVG 输出中不起作用

  • #4055: graphviz: :align: center 选项在 latex 输出中不起作用

  • #4051:warn() 函数在 HTML 主题中输出 ‘ None ‘ 字符串

Release 1.6.3（发布于 2017 年 7 月 2 日）

添加的特性

  • latex: 提示代码块将在下一页继续 (引用: #3764, #3792)

修复的错误

  • #3821: 无法在 Docutils 0.14rc1 中导入 sphinx.util.compat

  • #3829: sphinx-quickstart 模板对于使用 alabaster 不完整

  • #3772: ‘str对象’没有属性 ‘filename’

  • 如果引用标签包含连字符则发出错误警告 (refs: #3565)

  • #3858: 使用 –color 选项时某些警告未着色

  • #3775: 删除默认模板中的多余空白

  • #3835: sphinx.ext.imgmath无法转换项目目录名称包含空格的SVG图像

  • #3850: 修复make模式帮助命令中的颜色处理

  • #3865: 在Sphinx扩展中使用self.env.warn失败

  • #3824:自 Sphinx 1.6.1 以来,生产列表应用智能引号转换

  • latex: 修复 \sphinxbfcode 吞掉参数的初始空格

  • #3878: 自动文档化类属性中的引号在PDF输出中应为直引号

  • #3881: LaTeX 图形有时浮动到下一页,会留下额外的垂直空白

  • #3885: 重复的脚注引发 IndexError

  • #3873:sphinx.util.compat.Directive 的弃用警告机制失败

  • #3874: 针对跨文件引用的”引用未被引用”的错误警告

  • #3860: 当构建器不支持图片时,不下载图片

  • #3860: 无文件名的远程图像 URI 破坏不支持远程图像的构建器

  • #3833: 命令行消息在设置 language 时无意中被翻译.

  • #3840: 使检查 epub_uid 严格

  • #3851, #3706: 修复PDF输出的关于框绘制字符

  • #3900: autosummary 找不到方法

  • #3902: 如果 latex_documents 在 py2 中包含非 unicode 字符,则发出错误

版本 1.6.2（发布于 2017年5月28日）

不兼容的更改

  • #3789: 不需要为 python>=3.5 输入 typing 模块

修复的错误

  • #3754: 如果HTML主题附加自己的样式表,HTML生成器崩溃

  • #3756: epub: 实体 ‘mdash’ 未定义

  • #3758: 如果在conf.py中生成日志,Sphinx会崩溃

  • #3755: 错误地警告关于literalinclude的缩进问题

  • #3742:RTD Sphinx自有文档的PDF构建缺少书签和目录中的索引条目.这个问题是 rtfd/readthedocs.org#2857 ,解决方法是在Sphinx的:file:conf.py 中使用一些额外的LaTeX代码

  • #3770: 当 “code-block” 有选项 emphasize-lines 且所指示的行号高于实际行数时构建失败

  • #3774: 使用引用时增量HTML生成损坏

  • #3763:如果设置了 epub_cover,则会出现 epubcheck 验证错误

  • #3779: 因为 ‘sys.meta_path’ 出现错误导致在 sphinx.ext.autodoc 中出现 ‘ImportError’.感谢 Tatiana Tereshchenko.

  • #3796: 当给定非文档节点时,env.resolve_references() 崩溃

  • #3803: Sphinx 在处理无效的 PO 文件时崩溃

  • #3791:长表格的PDF”续下页”未国际化

  • #3788:smartquotes 为不支持的语言发出警告

  • #3807: latex Makefile 仅适用于 Unix 系统的 make latexpdf

  • #3781: 选项指令中的双破折号被编译为长破折号

  • #3817: latex 构建器引发 AttributeError

版本 1.6.1 （发布于 2017 年 5 月 16 日）

依赖项

1.6b1

  • (更新) latex 输出已在 Ubuntu trusty 的 texlive 包（2014 年 2 月）中进行了测试,早期的 tex 安装可能不完全符合标准,特别是在 Unicode 引擎 xelatex 和 lualatex 方面

  • (已添加) 在GNU/Linux和Mac OS X上,执行 make latexpdf 需要latexmk（参考: #3082）

不兼容的更改

1.6b1

  • #1061, #2336, #3235: 现在自动摘要的生成默认不包含导入的成员.感谢 Luc Saffre.

  • LaTeX \includegraphics 命令没有被重载:只有 \sphinxincludegraphics 具有自定义代码,以适应可用宽度（如果图片过大）.

  • The subclasses of sphinx.domains.Index should override generate() method. The default implementation raises NotImplementedError

  • LaTeX将长表格水平居中,而短表格靠左排列（表格周围没有文本流动）.现在在这两种情况下,默认位置均为居中,并且会遵守Docutils 0.13的 :align: 选项（参考 #3415, #3377）.

  • option指令还允许选项名称使用所有标点符号（参考:#3366）

  • #3413: 如果使用了 literalinclude 的 :start-after: ,使 :lines: 变为相对的 (参考 #3412)

  • literalinclude directive does not allow the combination of :diff: option and other options (refs: #3416)

  • LuaLaTeX引擎使用 fontspec ,就像XeLaTeX一样.建议 latex_engine = 'lualatex' 仅在最新的TeX安装中使用（参考#3070,#3466）

  • latex_keep_old_macro_names 的默认值已从 True 更改为 False .这意味着某些LaTeX宏的样式默认仅使用带有 `` ensphinx..`` 前缀的名称进行定义. （参考:#3429）

  • LaTeX longtable的页脚”继续在下一页”现在没有边框（参考:#3497）

  • #3529:BuildEnvironment.__init__ 的参数已更改

  • #3082: 在PDF（和DVI）目标中使用latexmk（仅限类Unix平台）

  • #3558: 如果脚注和引用未被引用,则发出警告.可以通过 suppress_warnings 来抑制这些警告.

  • latex 提供了来自与 pdftex 引擎一起分发的文件的（未文档化的）颜色宏.这被移除,以便更好地支持多个 TeX 引擎. Sphinx latex 编写器的扩展只能使用 color 或 xcolor 包的接口.（参考 #3550）

  • Builder.env is not filled at instantiation

  • #3594: LaTeX: 单个原始指令被视为块级元素

  • #3639: 如果 html_experimental_html5_writer 可用,epub 构建器默认使用它.

  • Sphinx.add_source_parser() raises an error if duplicated

1.6b2

  • #3345: 用Docutils的smart_quotes替换自定义的smartypants代码.感谢Dmitry Shachnev和Docutils的Günter Milde.

1.6b3

  • LaTeX 包 eqparbox 不再被 Sphinx 使用和加载

  • LaTeX 包 multirow 不再被 Sphinx 使用和加载

  • 在标准域中为引用数据添加行号

1.6 最终版

  • LaTeX包 threeparttable 不再被Sphinx使用和加载（参考 #3686, #3532, #3377）

移除的特性

  • 配置变量

    • epub3_contributor

    • epub3_description

    • epub3_page_progression_direction

    • html_translator_class

    • html_use_modindex

    • latex_font_size # LaTeX 字体大小

    • latex_paper_size

    • latex_preamble

    • latex_use_modindex

    • latex_use_parts

  • termsep node

  • defindex.html 模板

  • LDML format support in today, today_fmt and html_last_updated_fmt

  • :inline: option for the directives of sphinx.ext.graphviz extension

  • sphinx.ext.pngmath 扩展

  • sphinx.util.compat.make_admonition()

添加的特性

1.6b1

  • #3136: 为 sphinx.ext.graphviz 中的指令添加 :name: 选项

  • #2336: 为 sphinx-autogen 命令添加 imported_members 选项以文档化导入的成员.

  • C++,在模板声明中添加 :tparam-line-spec: 选项.指定后,每个模板参数将被渲染在单独的一行上.

  • #3359: 允许在用户本地目录中的 sphinx.js 覆盖 Sphinx 的 sphinx.js

  • #3303: 为 doctest 指令添加 :pyversion: 选项.

  • #3378: (latex) 支持表格指令的 :widths: 选项 (参考: #3379, #3381)

  • #3402: 允许使用 suppress_warnings 来抑制 “下载文件不可读” 的警告.

  • #3377: latex: 为表格添加对 Docutils 0.13 :align: 选项的支持（但不实现文本环绕表格）.

  • latex: 表格内部的脚注是超链接的（标题或表头除外）（参考: #3422）

  • 如果在 literalinclude 指令上检测到过度缩进,则发出警告（参考:#3416）

  • 对于LuaLaTeX使用与XeLaTeX相同的默认设置（即 fontspec 和 polyglossia ）. （参考:#3070,#3466）

  • 使 'extraclassoptions' 键的 latex_elements 公开 (参考 #3480)

  • #3463: 为必需的EPUB3元数据添加警告信息.为 epub_description 添加默认值,以避免类似其他设置的警告.

  • #3476: setuptools: 支持多种构建器

  • latex: LaTeX 表格中的合并单元格允许代码块、列表、引用块等,普通单元格也支持这些功能 (参考: #3435)

  • 如果 html_experimental_html5_writer 设置为 True 且安装了 Docutils 0.13 或更高版本,则 HTML 构建器使用实验性的 HTML5 写入器.

  • 在PDF输出中自定义表格前后的空白的LaTeX宏（参考#3504）

  • #3348: 在 literalinclude 和 viewcode 指令中显示装饰器

  • #3108: 如果 :start-at: 和其他 literalinclude 选项与文本不匹配,则显示警告

  • #3609: 允许使用 suppress_warnings 来抑制 “重复引用” 警告

  • #2803: 通过入口点发现构建器

  • #1764, #1676: 允许为样式表设置’rel’和’title’属性

  • #3589: 支持在非HTML构建器上使用远程图像

  • #3589: 在非HTML生成器中支持Data URI格式的图片

  • #2961: 改进了 autodoc_mock_imports .现在配置值只需要声明应该被模拟的顶层模块.感谢 Robin Jarry.

  • #3449: 在py3中,autodoc使用inspect.signature以更准确地计算签名.感谢Nathaniel J. Smith.

  • #3641: Epub 主题支持由 HTML5 写入器生成的 HTML 结构.

  • #3644: autodoc使用inspect而不是检查类型.感谢Jeroen Demeyer.

  • 添加一个新的扩展; sphinx.ext.imgconverter .它将文档中的图像转换为构建器的适当格式

  • latex: 使用模板渲染表格（参考 #3389, 2a37b0e）

1.6b2

  • LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass options to latexmk when executing make latexpdf (refs #3695, #3720)

  • 添加一个新的事件 env-check-consistency 用于检查扩展的一致性

  • 添加 Domain.check_consistency() 以检查一致性

修复的错误

1.6b1

  • literalinclude directive expands tabs after dedent-ing (refs: #3416)

  • #1574: 表格单元格中的段落在Latex输出中不起作用

  • #3288: 合并标题的表格不自动换行

  • #3491:PDF中表格和长表格周围不一致的垂直间距

  • #3506: HTML写入器的所有警告的离开函数现在正确地将 node 传递给 depart_admonition .

  • #2693: Sphinx latex 样式文件错误地抑制了 latex+dvi(ps,pdf,pdfmx) 的节标题颜色

  • C++,正确查找 any 引用.

  • #3624: sphinx.ext.intersphinx无法加载用gzip压缩的库存

  • #3551: PDF信息字典缺少作者和标题数据

  • #3351: intersphinx 不引用上下文,如 py:module 、 py:class 等.

  • 如果父模板被归档,则无法加载模板文件

1.6b2

  • #3661: sphinx-build 在并行构建时崩溃

  • #3669: gettext生成器失败,出现”ValueError: 未找到子字符串”

  • #3660: Sphinx始终依赖于sphinxcontrib-websupport及其依赖项

  • #3472: 智能引号在latex中出错（至少在通过autoattribute处理字符串列表时）(参考: #3345, #3666)

1.6b3

  • #3588: 即使在 html_compact_lists 为 True 的情况下,在 i18n 文档构建中也没有生成紧凑的 (p 标签) HTML 输出.

  • The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using latexmk) aborted earlier in case of LaTeX errors than was the case with 1.5 series, due to hard-coded usage of --halt-on-error option (refs #3695)

  • #3683: 默认未提供 sphinx.websupport 模块

  • #3683: 如果调用 builder.css_file.insert(),构建文档失败

  • #3714: viewcode 扩展未考虑 highlight_code='none'

  • #3698: 将 :doc: 移动到标准域导致向后兼容性破坏

  • #3633: 错误检测未引用的引用

1.6 最终版

  • LaTeX 表格不允许在表头单元格中使用多个段落

  • LATEXOPTS没有正确传递给pdflatex,自1.6b3以来

  • #3532:短表格单元中的图形或文字块标题导致PDF输出混乱

  • 修复:在PDF中,表格的标题渲染方式在使用longtable类时与不使用该类时有所不同（参考 #3686）

  • #3725: Todo在LaTeX输出中与note看起来不同

  • #3479: 存根列在LaTeX输出中没有效果

  • #3738: theming.py 中的无意义代码

  • #3746:由于未定义选项 -pdfxe 和 -pdflua ,使用 latexmk 4.48 或更早版本时 PDF 构建失败

过时

1.6b1

  • sphinx.util.compat.Directive class is now deprecated. Please use instead docutils.parsers.rst.Directive

  • sphinx.util.compat.docutils_version is now deprecated

  • #2367:Sphinx.warn() , Sphinx.info() 以及其他日志记录方法现已弃用.请改用 sphinx.util.logging (Logging API ).

  • #3318:notice 现在已被弃用作为 LaTeX 环境名称,将在 Sphinx 1.7 中移除.扩展作者请使用 sphinxadmonition 代替（自 1.5 版起 Sphinx 就已使用）.

  • Sphinx.status_iterator() and Sphinx.old_status_iterator() is now deprecated. Please use sphinx.util:status_iterator() instead.

  • Sphinx._directive_helper() is deprecated. Please use sphinx.util.docutils.directive_helper() instead.

  • BuildEnvironment.set_warnfunc() is now deprecated

  • 以下的 BuildEnvironment 方法现在已被弃用.

    • BuildEnvironment.note_toctree()

    • BuildEnvironment.get_toc_for()

    • BuildEnvironment.get_toctree_for()

    • BuildEnvironment.create_index()

    请使用 sphinx.environment.adapters 模块.

  • latex 包 footnote 不再通过其捆绑替代品 footnotehyper-sphinx 加载.重定义的宏与原始包中保持相同的名称.

  • #3429: 废弃配置设置 latex_keep_old_macro_names .它将在1.7版本中移除,且其默认值已从 True 改为 False .

  • #3221: epub2 构建器已被弃用

  • #3254:sphinx.websupport 现在分离为独立包 sphinxcontrib-websupport . sphinx.websupport 将在 Sphinx 2.0 中被移除.

  • #3628:sphinx_themes 入口点已弃用.请改用 sphinx.html_themes .

1.6b2

  • #3662:builder.css_files 已被弃用.请改用 add_stylesheet() API.

1.6 最终版

  • LaTeX \sphinxstylethead 在 1.6 版本中已弃用,将在 1.7 版本中删除.请将自定义内容迁移到新的宏 \sphinxstyletheadfamily 中.

测试

1.6 最终版

  • #3458: 添加 sphinx.testing （实验性）

发布 1.6（尚未发布）

  • 未发布（因软件包脚本错误）