Sphinx 1.6

版本 1.6.7 (发布于 2018年2月4日)

修复的 Bug

  • #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 生成的错误 map ID 的解决方案

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

  • #3953: 存在可用的 intersphinx 清单时不发出警告

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

  • #2372: autosummary: 类型标注函数的签名显示不正确

  • #3942: HTML：即使 :align: center，表格也不居中对齐

版本 1.6.6 (发布于 2018年1月8日)

新增功能

  • #4181: autodoc: 尽可能对字典键进行排序

  • VerbatimHighlightColor 是一个新的 LaTeX ‘sphinxsetup’ 键 (refs: #4285)

  • 更轻松地自定义代码块渲染中涉及的 LaTeX 宏

  • 如果 conf.py 引发异常，则显示回溯 (refs: #4369)

  • 添加 smartquotes 通过 conf.py 禁用智能引号 (refs: #3967)

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

修复的 Bug

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

  • #4206: latex: 段落间的 reST 标签丢失段落分隔符

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

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

  • #2298: automodule 未能文档化类属性

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

  • #4267: Unicode U+2116 NUMERO SIGN 字符导致 PDF 构建中断

  • #4249: PDF 输出：Pygments 错误高亮增加了代码块中的行距

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

  • #4279: 当使用多个进程和远程图像运行时，Sphinx 因 pickling 错误而崩溃

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

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

  • #4315: 对于 PDF “howto” 文档，latex_toplevel_sectioning='part' 生成 \chapter 命令

  • #4214: 两个 todolist 指令中断 Sphinx 1.6.5

  • 修复与 intersphinx 的外部选项文档的链接 (refs: #3769)

  • #4091: 私有成员在没有 :undoc-members 的情况下未文档化

版本 1.6.5 (发布于 2017年10月23日)

新增功能

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

  • #4112: 如果 smart_quotes 设置已设置，则不要覆盖它

  • #4125: 在 i18n 警告消息中显示原始和翻译段落的参考文本

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

修复的 Bug

  • #4085: 使用 :align: 选项在解析文字中包含图像导致 PDF 构建失败

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

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

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

  • #4070, #4111: 警告消息包含格式字符串时崩溃 (再次)

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

  • #3692: 如果 writing .buildinfo 失败，则无法构建 HTML

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

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

  • #4134: [doc] docutils.conf 未明确文档化

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

  • #1020: ext.todo todolist 未链接到 pdflatex 中的页面

  • #3965: 新的 quickstart 在 Makefile 中生成错误的 SPHINXBUILD

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

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

  • #4090: [doc] 带有额外 LaTeX 宏的 latex_additional_files 不应使用 .tex 扩展名

  • 未能将 reST 解析器错误转换为警告 (refs: #4132)

版本 1.6.4 (发布于 2017年9月26日)

新增功能

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

修复的 Bug

  • #3924: 在扩展中动态解析 RST 后 docname 丢失

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

  • pep:

    和 :rfc: 不支持 default-role 指令 (refs: #3960)

  • #3960: default_role = ‘guilabel’ 不起作用

  • Windows 上 latexpdf 构建器中缺少 texinputs_win/Makefile。

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

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

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

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

  • #4041: C++，删除函数指针中额外的名称链接。

  • #4038: C，添加缺少 member 角色的文档。

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

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

  • #4062: hashlib.sha1() 必须接受字节，而不是 Python 3 上的 unicode

  • 避免 latex 中索引条目后的缩进 (refs: #4066)

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

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

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

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

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

版本 1.6.3 (发布于 2017年7月2日)

新增功能

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

修复的 Bug

  • #3821: 无法使用 Docutils 0.14rc1 导入 sphinx.util.compat

  • #3829: sphinx-quickstart 模板在使用 alabaster 方面不完整

  • #3772: 'str object' 没有属性 '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: 如果 py2 中 latex_documents 包含非 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 自己的 conf.py 中使用一些额外的 LaTeX 代码获得了解决方案

  • #3770: 当“code-block”具有 emphasize-lines 选项且指示的数字大于行数时，构建失败

  • #3774: 使用引用时，增量 HTML 构建中断

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

  • #3779: sphinx.ext.autodoc 中由于损坏的 'sys.meta_path' 导致 'ImportError'。感谢 Tatiana Tereshchenko。

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

  • #3803: Sphinx 因无效的 PO 文件而崩溃

  • #3791: PDF 长表格的“continued on next page”未国际化

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

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

  • #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 (refs: #3082)

不兼容的更改

1.6b1

  • #1061, #2336, #3235: 现在 autosummary 默认不包含导入的成员。感谢 Luc Saffre。

  • LaTeX \includegraphics 命令未重载：只有 \sphinxincludegraphics 具有自定义代码，可在图像过大时适应可用宽度。

  • sphinx.domains.Index 的子类应重写 generate() 方法。默认实现引发 NotImplementedError

  • LaTeX 将长表格水平居中放置，短表格左对齐 (表格周围没有文本流)。现在，两种情况下的位置都默认为居中，并将遵循 Docutils 0.13 :align: 选项 (refs #3415, #3377)

  • option 指令也允许所有标点符号作为选项名称 (refs: #3366)

  • #3413: 如果使用了 literalinclude 的 :start-after:，则使 :lines: 相对 (refs #3412)

  • literalinclude 指令不允许 :diff: 选项与其他选项组合使用 (refs: #3416)

  • LuaLaTeX 引擎使用 fontspec，类似于 XeLaTeX。建议 latex_engine = 'lualatex' 仅在最新的 TeX 安装上使用 (refs #3070, #3466)

  • latex_keep_old_macro_names 默认值已从 True 更改为 False。这意味着一些用于样式的 LaTeX 宏默认仅使用 \sphinx.. 前缀名称定义。(refs: #3429)

  • LaTeX longtable 的页脚“Continued on next page”现在没有边框 (refs: #3497)

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

  • #3082: 对 pdf (和 dvi) 目标使用 latexmk (仅限类 Unix 平台)

  • #3558: 如果脚注和引用未被引用，则发出警告。警告可以通过 suppress_warnings 抑制。

  • latex 提供了 (未文档化) 颜色宏，这些宏来自 pdftex 引擎随附的 Plain TeX 文件。为了更好地支持多个 TeX 引擎，此功能已删除。Sphinx latex 写入器的扩展只能使用 color 或 xcolor 包中的接口。(refs #3550)

  • Builder.env 在实例化时未填充

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

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

  • Sphinx.add_source_parser() 如果重复则引发错误

1.6b2

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

1.6b3

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

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

  • 向 std 域中的引用数据添加行号

1.6 正式版

  • LaTeX 包 threeparttable 不再被 Sphinx 使用和加载 (refs #3686, #3532, #3377)

已移除的功能

  • 配置变量

    • epub3_contributor

    • epub3_description

    • epub3_page_progression_direction

    • html_translator_class

    • html_use_modindex

    • latex_font_size

    • latex_paper_size

    • latex_preamble

    • latex_use_modindex

    • latex_use_parts

  • termsep 节点

  • defindex.html 模板

  • today, today_fmt 和 html_last_updated_fmt 中的 LDML 格式支持

  • sphinx.ext.graphviz 扩展指令的 :inline: 选项

  • 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: 选项 (refs: #3379, #3381)

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

  • #3377: latex: 添加对 Docutils 0.13 :align: 选项的支持，用于表格 (但未实现表格周围的文本流)。

  • latex: 表格内部的脚注带有超链接 (标题或页眉除外) (refs: #3422)

  • 如果 literalinclude 指令检测到过多的缩进，则发出警告 (refs: #3416)

  • LuaLaTeX 使用与 XeLaTeX 相同的默认设置 (即 fontspec 和 polyglossia)。(refs: #3070, #3466)

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

  • #3463: 为所需的 EPUB3 元数据添加警告消息。为 epub_description 添加默认值以避免像其他设置一样的警告。

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

  • latex: LaTeX 表格中的合并单元格允许代码块、列表、块引用等，就像普通单元格一样 (refs: #3435)

  • 如果 html_experimental_html5_writer 为 True 且安装了 Docutils 0.13 或更高版本，HTML 构建器将使用实验性 HTML5 写入器。

  • 用于在 PDF 输出中自定义表格前后空间的 LaTeX 宏 (refs #3504)

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

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

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

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

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

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

  • #3589: 支持非 HTML 构建器上的数据 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: 使用模板渲染表格 (refs #3389, 2a37b0e)

1.6b2

  • $BUILDDIR/latex 中的 Makefile 的 LATEXMKOPTS 变量，用于在执行 make latexpdf 时将选项传递给 latexmk (refs #3695, #3720)

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

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

修复的错误

1.6b1

  • literalinclude 指令在取消缩进后展开制表符 (refs: #3416)

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

  • #3288: 带有合并标题的表格不换行

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

  • #3506: HTML 写入器中所有训诫的 depart 函数现在正确地将 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: substring not found”

  • #3660: Sphinx 总是依赖 sphinxcontrib-websupport 及其依赖项

  • #3472: latex 中的智能引号出现错误 (至少对于通过 autoattribute 的字符串列表) (refs: #3345, #3666)

1.6b3

  • #3588: 即使 html_compact_lists 为 True，i18n 文档构建中也没有紧凑 (p 标签) 的 html 输出。

  • 1.6b1 的 make latexpdf (适用于 GNU/Linux 和 Mac OS，使用 latexmk) 在 LaTeX 错误时比 1.5 系列更早中止，原因是硬编码使用了 --halt-on-error 选项 (refs #3695)

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

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

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

  • #3698: 将 :doc: 移动到 std 域破坏了向后兼容性

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

1.6 正式版

  • LaTeX 表格不允许标题单元格中包含多个段落

  • 自 1.6b3 以来，LATEXOPTS 未正确传递给 pdflatex

  • #3532: 短表格单元格中的图或文字块标题在 PDF 输出中造成混乱

  • 修复：在 PDF 中，表格标题的渲染方式因表格是否属于 longtable 类而异 (refs #3686)

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

  • #3479: stub-columns 在 LaTeX 输出中无效

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

  • #3746: 由于未定义的选项 -pdfxe 和 -pdflua，PDF 构建在 latexmk 4.48 或更早版本上失败

已弃用

1.6b1

  • sphinx.util.compat.Directive 类现已弃用。请改用 docutils.parsers.rst.Directive

  • sphinx.util.compat.docutils_version 现已弃用

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

  • #3318: notice 作为 LaTeX 环境名称现已弃用，并将在 Sphinx 1.7 中移除。扩展作者请改用 sphinxadmonition (Sphinx 自 1.5 以来一直如此)。

  • Sphinx.status_iterator() 和 Sphinx.old_status_iterator() 现已弃用。请改用 sphinx.util:status_iterator()。

  • Sphinx._directive_helper() 已弃用。请改用 sphinx.util.docutils.directive_helper()。

  • BuildEnvironment.set_warnfunc() 现已弃用

  • 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 entry_point 已弃用。请改用 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 (未发布)

  • 未发布 (因为包脚本错误)