Sphinx 1.4¶

发布 1.4.9 (2016 年 11 月 23 日发布)¶

修复的 Bug¶

#2936: 修复 doc/Makefile 无法构建 man 的问题，因为 doc/man 存在。
#3058: 在多个 'toctree' 指令中使用相同的 'caption' 属性会导致警告/错误。
#3068: 允许在 sphinx-build.py 的 -D 选项中使用 '=' 字符。
#3074: add_source_parser() 在调试模式下崩溃。
#3135: sphinx.ext.autodoc 崩溃，并带有纯 Callable。
#3150: 修复 JavaScript 中的查询词拆分器。它与 Python 的正则表达式行为相同。
#3093: gettext 构建在替换图像上中断。
#3093: gettext 构建在 note 指令下的图像节点上中断。
imgmath: 如果图像生成失败，显示错误消息时崩溃。
#3117: LaTeX 写入器在 admonition 放置在第一个节标题之前时崩溃。
#3164: 更改 sphinx.ext.inheritance_diagram 的搜索顺序。

发布 1.4.8 (2016 年 10 月 1 日发布)¶

修复的 Bug¶

#2996: Sphinx 的 wheel 包因 ImportError 崩溃。

发布 1.4.7 (2016 年 10 月 1 日发布)¶

修复的 Bug¶

#2890: Quickstart 在所有错误条件下应一致返回错误。
#2870: 扁平化 genindex 列的高度。
#2856: 生成的 HTML 网站上的搜索无法找到某些符号。
#2882: 在 linkcheck 中，如果状态为 403，则回退到 GET 请求。
#2902: 如果关键字以下划线开头，jsdump.loads 无法加载搜索索引。
#2900: 修复 epub content.opf: 将自动生成的孤立文件添加到 spine。
#2899: 修复 Jinja2 模板中的 hasdoc() 函数。它也将检测 genindex 和 search。
#2901: 修复 epub 结果: 跳过创建从图像标签到原始图像文件的链接。
#2917: HTML 中行内代码断字。
#1462: autosummary 对带有尾随下划线属性的 namedtuple 发出警告。
如果指定了 :nowrap: 选项，则无法引用方程。
#2873: LaTeX 中代码块溢出 (由于逗号)。
#1060, #2056: sphinx.ext.intersphinx: 如果在 intersphinx_mapping 中使用相对路径，则生成损坏的链接。
#2931: 带有相同 :caption: 的代码块指令会导致重复目标的警告。现在 code-block 和 literalinclude 不会自动使用其标题定义超链接目标。
#2962: latex: 缺少 longtable 的标签。
#2968: autodoc: show-inheritance 选项破坏 docstring。

发布 1.4.6 (2016 年 8 月 20 日发布)¶

不兼容的变更¶

#2867: linkcheck 构建器在 six-1.4 下崩溃。现在 Sphinx 依赖于 six-1.5 或更高版本。

修复的 Bug¶

applehelp: 如果未找到 hiutil 或 codesign 命令，Sphinx 会崩溃。
修复当构建目录包含像 DS_Store 这样的常规文件时 make clean 中止的问题。
减少 epubcheck 警告/错误。
- 将 DOCTYPE 修复为 html5。
- 将扩展名从 .html 更改为 .xhtml。
- 禁用 epub 结果中的搜索页面。
#2778: 修复 autodoc 在 obj.__dict__ 是属性方法并引发异常时崩溃的问题。
修复 epub3 输出中重复的 toc。
#2775: 修复 linkcheck 因服务器不支持 identity 编码而失败的问题。
#2833: 修复 ext.autodoc 中实例注释的格式问题。
#1911: sphinx-build 的 -D 选项不会覆盖 extensions 变量。
#2789: 如果提供了清单，sphinx.ext.intersphinx 会生成错误的超链接。
文档中显示代码块标题的解析错误 (参考: #2845)。
#2846: singlehtml 构建器不包含图号。
#2816: 修复构建数据占用 Domain.initial_data 类属性的问题。

发布 1.4.5 (2016 年 7 月 13 日发布)¶

不兼容的更改¶

latex，从图像指令中包含非行内图像会导致根据原始图像宽度而产生不一致的空白；新行为在某些情况下必然与早期行为不同。(参考: #2672)
latex，使用 \includegraphics 引用 Sphinx 自定义变体已被弃用；将来它将恢复为原始 LaTeX 宏，自定义宏已有一个替代名称 \sphinxincludegraphics。

新增功能¶

新的配置选项 latex_keep_old_macro_names，默认为 True。如果为 False，则宏（用于文本样式）仅使用 \sphinx 前缀名称定义。
latex 写入器允许用户通过三个长度变量自定义“阴影”框（主题）。
epub 构建器现在支持 woff 格式的 Web 字体文件。

修复的 Bug¶

jsdump 修复 python 3：修复 python > 3 上的 HTML 搜索。
#2676: (latex) 自 Sphinx 1.4.4 起，标题中的 verbatim 文本出错。
#2629: memoir 类导致 LaTeX 崩溃。通过 latex_keep_old_macro_names=False 修复 (参考 2675)。
#2684: sphinx.ext.intersphinx 在 six-1.4.1 下崩溃。
#2679: 'figure_align': 'H' latex 选项需要 float 包。
#2671: 图像指令可能导致 pdf 中间距不一致。
#2705: 如果指定了 :titlesonly:，toctree 会生成空的 bullet_list。
#2479: sphinx.ext.viewcode 默认使用 python2 高亮器。
#2700: HtmlHelp 构建器硬编码 index.html。
latex，自 1.4.4 起，行内 literal 文本后面会有一个多余的空格。
#2722: C++，修复变量/成员声明的 ID 生成以包含命名空间。
latex，列表或引用块中的图像（来自图像指令）不遵守缩进（与 #2671 一起修复）。
#2733: 自 Sphinx 1.4.4 起，make latexpdf 会生成大量 hyperref 警告。
#2731: sphinx.ext.autodoc 不访问引发任何异常的 propertymethods。
#2666: C++，正确查找涉及构造函数的嵌套名称。
#2579: 无法通过 sphinx.ext.intersphinx 引用包含空格和冒号的标签。
#2718: 如果文档文件不可读，Sphinx 会崩溃。
#2699: 如果设置了 html_file_suffix，帮助 HTML 中的超链接会损坏。
#2723: latex pdf 输出中多行单元格的额外空格。
#2735: latexpdf Underfull \hbox (badness 10000) 来自标题页的警告。
#2667: 如果调整大小的图像出现在节标题中，latex 会崩溃。
#2763: (html) 为 SVG 源图像标签的必需 alt 属性提供默认值，这是验证所必需的，现在与其他格式一致。

发布 1.4.4 (2016 年 6 月 12 日发布)¶

修复的 Bug¶

#2630: latex: sphinx.sty notice 环境格式问题。
#2632: 警告指令在 quote 环境 latex 构建中失败。
#2633: Sphinx 在旧式索引下崩溃。
修复 sphinx.sty 1.4.2 中 \begin{\minipage} 的拼写错误 (参考: 68becb1)。
#2622: LaTeX 在标题和目录后产生空页。
#2640: 1.4.2 LaTeX 如果警告指令内有代码块，则崩溃。
让 LaTeX 在行内代码中也使用直引号 (参考 #2627)。
#2351: 如果枚举列表放在脚注中，latex 会崩溃。
#2646: 如果数学包含两次空行，latex 会崩溃。
#2480: sphinx.ext.autodoc: 显示内存地址。
latex: 允许代码块出现在列表和引用中，最大嵌套深度 (参考 #777, #2624, #2651)。
#2635: Latex 代码指令根据查看分辨率产生不一致的框架。
#2639: Sphinx 现在捆绑 iftex.sty。
无法使用 framed.sty 0.95 构建 PDF。
Sphinx 现在捆绑 needspace.sty。

发布 1.4.3 (2016 年 6 月 5 日发布)¶

修复的 Bug¶

#2530: 如果 admonition 中存在大量编号的脚注，则构建 PDF 时出现“计数器过大”错误。
如果同时指定了 align 选项，则 figure 指令的 width 选项不起作用 (参考: #2595)。
#2590: inputenc 包会破坏 lualatex 和 xelatex 的编译。
#2540: latex 首页日期使用不同的字体。
如果文档已包含在 toctree 中，则抑制“文档未包含在任何 toctree 中”的警告 (参考: #2603)。
#2614: 如果用户在序言中设置了非零段落缩进，PDF 输出中的某些表格将最终移位。
#2602: URL 重定向破坏了 sphinx.ext.intersphinx 生成的超链接。
#2613: 如果加载了合并的扩展，则显示警告。
#2619: 确保始终加载 amstext LaTeX 包 (参考: d657225, 488ee52, 9d82cad 和 #2615)。
#2593: 如果表格中有任何图形，latex 会崩溃。

发布 1.4.2 (2016 年 5 月 29 日发布)¶

新增功能¶

现在 suppress_warnings 接受以下配置 (参考: #2451, #2466)
- app.add_node
- app.add_directive
- app.add_role
- app.add_generic_role
- app.add_source_parser
- image.data_uri
- image.nonlocal_uri
#2453: LaTeX 写入器允许在主题内容中分页；并且它们的水平范围现在适合行宽（带有边距阴影）。此外，警告类型的 admonition 允许分页，并且它们的垂直间距已与提示类型通知的间距更加一致（参考 #2446）。
#2459: LaTeX 输出中文字代码块的框架（不仅仅是代码行本身）遵循列表或引用块中的缩进。
#2343: LaTeX 输出中，代码块中的长源行会被换行（不修改行号）(参考 #1534, #2304)。

Bug 修复¶

#2370: LaTeX 写入器中方程略有错位。
#1817, #2077: 抑制 sphinx-quickstart 生成的 conf.py 中的 pep8 警告。
#2407: 如果文档包含大型数据图像 URI，则构建文档时崩溃。
#2436: 如果加载扩展失败，Sphinx 不会通过 needs_sphinx 检查版本。
#2397: 为土耳其文档设置 shorthandoff。
#2447: VerbatimBorderColor 也错误地用于 PDF 标题。
#2456: C++，修复与文档合并相关的崩溃（例如，singlehtml 和 Latex 构建器）。
#2446: latex(pdf) 将本地目录（或更一般地说主题节点）设置为不可中断的框，导致底部溢出。
#2476: 如果给定 :nowrap:，则省略 MathJax 标记。
#2465: 如果未向 toctree 指令提供标题选项，则 latex 构建器失败。
如果发现自引用 toctree，Sphinx 会崩溃。
#2481: mecab 搜索拆分器拼写错误。感谢 Naoki Sato。
#2309: 修复无法通过 ref-role 引用“间接超链接目标”的问题。
如果映射 URL 包含任何端口，intersphinx 会失败。
#2088: 如果映射 URL 需要基本身份验证，intersphinx 会崩溃。
#2304: latexpdf 代码块中的自动换行。
#1534: Latex verbatim 块中的长行自动换行。
#2460: PDF 输出中，带标题的文字块顶部有太多空白。
加载多个数学扩展时显示错误原因 (参考: #2499)。
#2483: 如果图形标题只包含非文本对象，则不分配任何图形编号。
#2501: Unicode 下标数字在 LaTeX 中被规范化。
#2492: 带有 :figwidth: 的 figure 指令生成不正确的 Latex 代码。
即使指定了 :align:，图形的标题也始终居中放置。
#2526: 如果只有图像，LaTeX 写入器会崩溃。
#2522: Sphinx 触及已安装目录下的 mo 文件，导致权限错误。
#2536: C++，修复当紧邻嵌套范围与当前范围具有相同名称时发生的崩溃。
#2555: 修复带 unicode 的任何引用崩溃的问题。
#2517: 如果使用 LuaLaTeX，PDF 中的书签编码错误。
#2521: 如果未找到 sphinx-build，生成的 Makefile 导致 BSD make 崩溃。
#2470: typing backport 包导致 python 2.7 出现 autodoc 错误。
如果 intersphinx_mapping 的键使用了非字符串值，sphinx.ext.intersphinx 会崩溃。
#2518: intersphinx_mapping 不允许非字母数字键。
#2558: devhelp 构建器上的解包错误。
#2561: 当脚注包含链接时，Info 构建器崩溃。
#2565: sphinx.ext.autosummary 生成的对象描述在 LaTeX 写入器中溢出行。
在 sphinx.sty 中将 pdflatex 配置扩展到子段落 (参考: #2551)。
#2445: rst_prolog 和 rst_epilog 影响非 reST 源。
#2576: 如果子进程引发错误，sphinx.ext.imgmath 会崩溃。
#2577: sphinx.ext.imgmath: 将无效参数传递给 dvisvgm。
#2556: Xapian 搜索在 Python 3 中不起作用。
#2581: 如果 language="es"（西班牙语），搜索不起作用。
#2382: 调整 LaTeX 写入器中图形编号后缩写词的间距。
#2383: latex_show_urls 生成的脚注溢出行。
#2497, #2552: 搜索按钮的标签不适合按钮本身。

发布 1.4.1 (2016 年 4 月 12 日发布)¶

不兼容更改¶

today_fmt 和 html_last_updated_fmt 的默认格式又回到了 strftime 格式。为了向后兼容，直到 Sphinx 1.5，也支持 Locale Date Markup Language。

翻译¶

添加了威尔士语翻译，感谢 Geraint Palmer。
添加了希腊语翻译，感谢 Stelios Vitalis。
添加了世界语翻译，感谢 Dinu Gherman。
添加了印地语翻译，感谢 Purnank H. Ghumalia。
添加了罗马尼亚语翻译，感谢 Razvan Stefanescu。

修复的错误¶

C++，增加了对 extern 和 thread_local 的支持。
C++，类型声明现在根据声明样式使用前缀 typedef、using 和 type。
#2413: C++，修复重复声明的断言错误。
#2394: 当 html_last_updated_fmt 无效时，Sphinx 会崩溃。
#2408: Makefile 和 make.bat 中没有 dummy 构建器。
#2412: LaTeX 构建器中超链接目标损坏。
如果将非段落项作为标题，则 figure 指令会崩溃。
#2418: today_fmt 中不再允许时间格式。
#2395: 如果图像文件名中包含 unicode 字符，Sphinx 会崩溃。
#2396: genindex-single 中“解包值过多”错误。
#2405: PDF 中 numref 链接跳转到错误的位置。
#2414: PDF 超链接到代码列表时缺少编号。
#2440: gmtime 导入错误。感谢 Uwe L. Korn。

发布 1.4 (2016 年 3 月 28 日发布)¶

不兼容的更改¶

取消 PorterStemmer 包支持。使用 PyStemmer 代替 PorterStemmer 来加速词干提取。
sphinx_rtd_theme 已成为可选。请手动安装。参考 #2087, #2086, #1845 和 #2097。感谢 Victor Zverovich。
#2231: 在 LaTeX 写入器中为自定义角色使用 DUrole 而不是 DUspan。它允许将角色标题作为自定义宏的参数。
#2022: ‘Thumbs.db’ 和 ‘.DS_Store’ 已添加到 sphinx-quickstart 中提供的 conf.py 的 exclude_patterns 默认值中。
#2027, #2208: html_title 只接受字符串值。并且 None 值不能被接受。
sphinx.ext.graphviz: 默认情况下以内联方式显示图图像。
#2060, #2224: manpage 角色现在生成 sphinx.addnodes.manpage 节点而不是 sphinx.addnodes.literal_emphasis 节点。
#2022: html_extra_path 也会复制额外目录中的点文件，并参考 exclude_patterns 来排除额外文件和目录。
#2300: 增强 autoclass:: 以在 __init__ 方法缺失或为空时使用 __new__ 的 docstring。
#2251: 以前，在术语表指令下，一个定义的多个术语被转换为单个 term 节点，并且 term 节点中的每个术语由 termsep 节点分隔。在新实现中，每个术语都被转换为单独的 term 节点，并且 termsep 节点被移除。通过此更改，每个构建器的输出布局略有改变。
默认高亮语言现在是 Python 3。这意味着源代码被高亮为 Python 3（它主要是 Python 2 的超集），并且不尝试解析以区分有效代码。要恢复旧行为，请将 highlight_language = "python" 添加到 conf.py 中。
本地日期标记语言，例如 "MMMM dd, YYYY" 是 today_fmt 和 html_last_updated_fmt 的默认格式。但是，strftime 格式，例如 "%B %d, %Y" 也支持向后兼容，直到 Sphinx 1.5。后一种格式将从 Sphinx 1.5 开始禁用。
#2327: latex_use_parts 现在已弃用。请改用 latex_toplevel_sectioning。
#2337: 在 LaTeX 写入器中使用 \url{URL} 宏而不是 \href{URL}{URL}。
#1498: manpage 写入器: 如果定义列表中的项包含 strong 节点，则不要将其全部加粗。
#582: 删除 html 输出中快速搜索框的提示消息。
#2378: Sphinx 现在捆绑 newfloat.sty。

新增功能¶

#2092: 在 napoleon 包中添加 todo 指令支持。
#1962: 当从扩展中添加指令、角色或节点时，如果该元素已存在（内置或由另一个扩展添加），则发出警告。
#1909: 在 Intersphinx 清单中添加“doc”引用。
C++ 类型别名支持 (例如，.. type:: T = int)。
C++ 模板支持类、函数、类型别名和变量 (#1729, #1314)。
C++，添加了新的作用域管理指令 namespace-push 和 namespace-pop。
#1970: 用于导航下一主题和上一主题的键盘快捷键。
Intersphinx: 增加了对使用 HTTP 基本身份验证的 URL 获取 Intersphinx 清单的支持。
C++，增加了对函数信息字段列表中的模板参数的支持。
C++，增加了对成员（函数）指针的支持。
#2113: 允许 :class: 选项用于代码块指令。
#2192: Imgmath (带 svg 支持的 pngmath)。
#2200: 支持 LaTeX 构建器的 XeTeX 和 LuaTeX。
#1906: 对于 LaTeX 输出，如果可用，则对 fcolorbox 使用 xcolor 而不是 color。
#2216: Texinputs makefile 改进。
#2170: 支持中文搜索索引。
#2214: 添加 sphinx.ext.githubpages 以在 GitHub Pages 上发布文档。
#1030: 使 latex_show_pagerefs 的页面引用名称可翻译。
#2162: 添加 Sphinx.add_source_parser() 以从扩展添加 source_suffix 和 source_parsers。
#2207: 添加 sphinx.parsers.Parser 类；新解析器的基类。
#656: 添加 graphviz_dot 选项到 graphviz 指令以切换 dot 命令。
#1939: 添加了 dummy 构建器: 不带输出的语法检查。
#2230: 添加 math_number_all 选项以对数学扩展中的所有显示数学进行编号。
#2235: needs_sphinx 支持微版本比较。
#2282: 在“basic”主题中为 html 标签添加“language”属性。
#1779: 添加 EPUB 3 构建器。
#1751: 添加 todo_link_only 以避免在 todolist 上显示文件路径和行指示。感谢 Francesco Montesano。
#2199: 使用 imagesize 包获取图像大小。
#1099: 为 linkcheck 构建器添加可配置的重试。感谢 Alex Gaynor。此外，不检查以 ! 开头的锚点。
#2300: 增强 autoclass:: 以在 __init__ 方法缺失或为空时使用 __new__ 的 docstring。
#1858: 添加 Sphinx.add_enumerable_node() 以添加用于 numfig 功能的可枚举节点。
#1286, #2099: 添加 sphinx.ext.autosectionlabel 扩展以允许使用其标题引用节。感谢 Tadhg O’Higgins。
#1854: 允许选择 Janome 作为日语拆分器。
#1853: 支持在 html 搜索中使用 language='ja' 的自定义文本拆分器。
#2320: 术语表术语的分类器可用于索引条目分组键。分类器也可用于翻译。另请参阅术语表。
#2308: 定义 \tablecontinued 宏以重新定义 longtable 的持续标签样式。
如果多个图像通过 .. image:: filename.* 进行通配符匹配，则通过相似性选择图像。
#1921: 支持通过 language 和 figure_language_filename 进行图形替换。
#2245: 添加 latex_elements["passoptionstopackages"] 选项以在序言的早期阶段调用 PassOptionsToPackages。
#2340: 数学扩展: 支持 MathJax 多个方程的对齐。
#2338: 定义 \titleref 宏以重新定义 title-reference 角色的样式。
定义 \menuselection 和 \accelerator 宏以重新定义 menuselection 角色的样式。
定义 \crossref 宏以重新定义引用的样式。
#2301: 经典 html 主题中的文本应断字。
#2355: 定义 \termref 宏以重新定义 term 角色的样式。
添加 suppress_warnings 以抑制任意警告消息（实验性）。
#2229: 修复对未知选项没有警告的问题。
#2327: 添加 latex_toplevel_sectioning 以切换 LaTeX 文档的顶级分节。

Bug 修复¶

#1913: C++，修复枚举器在次全局和全局作用域中的断言错误。
C++，修复“signed char”和“unsigned char”作为类型的解析。
C++，添加对“friend”函数的缺失支持。
C++，添加对虚拟基类的缺失支持（感谢 Rapptz）。
C++，添加对最终类的支持。
C++，修复以“enum”为前缀的类型的解析。
#2023: 荷兰语搜索支持使用丹麦语词干提取信息。
C++，添加对用户定义字面量的支持。
#1804: 现在 html 输出在侧边栏中包裹溢出的长行文本。感谢 Hassen ben tanfous。
#2183: 修复 porterstemmer 导致 make json 失败。
#1899: 确保列表发送到 OptParse。
#2164: 修复 sphinx.sty 中 pdftex 的错误检查（用于 graphicx 包选项）。
#2165, #2218: 从 sphinx.sty 中移除错误的和不需要的条件。
修复如果给出未知语言则生成损坏的 LaTeX 代码的问题。
#1944: 修复 rst_prolog 破坏文件范围元数据的问题。
#2074: make gettext 应该使用 .pot 的规范相对路径。感谢 anatoly techtonik。
#2311: 修复 sphinx.ext.inheritance_diagram 引发 AttributeError 的问题。
#2251: .rst 文件中的换行符以错误的方式传输到 .pot 文件中。
#794: 修复 latex 输出中的日期格式未本地化的问题。
从 LaTeX 写入器的 supported_image_types 中移除 image/gif (#2272)。
修复当 LANGUAGE 为空字符串时引发 ValueError 的问题。
修复当使用 Sphinx.add_crossref_type 生成的指令时显示解包警告的问题。
默认高亮语言现在是 default。这意味着如果可能，源代码将被高亮显示为 Python 3（它主要是 Python 2 的超集）。要恢复旧行为，请将 highlight_language = "python" 添加到 conf.py。
#2329: 如果源目录已更改，则强制刷新环境。
#2331: 修复 dvi 中代码块被块填充的问题；从 xcolor 包中移除 xcdraw 选项。
修复当 unicode 被赋予需要字符串值的 confval 时 confval 类型检查器发出警告的问题。
#2360: 修复 LaTeX 输出中 numref 损坏的问题。
#2361: 修复“compound”指令内的额外段落缩进的问题。
#2364: 修复从旧版本升级 Sphinx 时出现的 KeyError ‘rootSymbol’。
#2348: 将 amsmath 和 amssymb 移到 LaTeX 写入器中 fontpkg 之前。
#2368: 默认情况下忽略 emacs 锁定文件，例如 .#foo.rst。
#2262: literal_block 及其标题在 LaTeX 输出中被分页符分隔。
#2319: 修复 LaTeX 中表格计数器被代码块覆盖的问题。感谢 jfbu。
修复与第三方域扩展结合使用时出现的解包警告。
#1153: 修复侧边栏中的图形导致 latex 构建错误。
#2358: 修复用户序言无法覆盖 tocdepth 定义的问题。
#2358: 如果 part 或 chapter 用于 top_sectionlevel，则减少 tocdepth。
#2351: 修复脚注间距。
#2363: 修复模板中的 toctree() 在 SingleHTMLBuilder 中生成损坏链接的问题。
#2366: 修复 HTML 构建器中 toctree 上生成空超链接的问题。

文档¶

#1757: 修复 html_last_updated_fmt 的用法。感谢 Ralf Hemmecke。