Sphinx 1.2¶
版本 1.2.3(发布于 2014 年 9 月 1 日)¶
新增功能¶
#1518:
sphinx-apidoc命令现在有一个--version选项,用于显示版本信息并退出。新区域设置:希伯来语、欧洲葡萄牙语、越南语。
修复的 Bug¶
#636: 在 LaTeX 构建中,保持字面块中的直单引号。
#1419: 生成的 i18n sphinx.js 文件缺少来自“.js_t”和“.html”的消息目录条目。此问题是在 Sphinx 1.1 中引入的。
#1363: 修复 i18n:缺少带有 currentmodule 指令或 currentclass 指令的 python 域的交叉引用。
#1444: autosummary 未从属性文档字符串创建描述。
#1457: 在 python3 环境中,当链接目标 URL 包含哈希部分时,linkcheck 导致“无法隐式将‘bytes’对象转换为 str”错误。感谢 Jorge_C。
#1467: 如果 automethod 指定了不存在的方法,则在 Python3 上出现异常。
#1441: autosummary 无法正确处理嵌套类。
#1499: 当 conf.py 中的
setup不可调用时,sphinx-build 现在会发出用户友好的错误消息。#1502: 在 autodoc 中,修复包含反斜杠的参数默认值的显示。
#1226: autodoc, autosummary:通过 automodule 导入 setup.py 将调用 setup 过程并执行
sys.exit()。现在 Sphinx 避免了 SystemExit 异常,并在没有意外终止的情况下发出警告。#1503: 当使用空列表
[]指定默认参数时,py:function 指令生成不正确的签名。感谢 Geert Jansen。#1508: 当进行 singlehtml、latex、man、texinfo 和 changes 构建时,非 ASCII 文件名会引发异常。
#1531: 在 Python3 环境中,docutils.conf 的 general 部分中包含“source_link=true”会导致类型错误。
PR#270, #1533: 当与 inheritance-diagram 指令一起使用时,非 ASCII 文档字符串会导致 UnicodeDecodeError。感谢 WAKAYAMA shirou。
PR#281, PR#282, #1509: TODO 扩展不兼容 websupport。感谢 Takeshi Komiya。
#1477: gettext 不提取表格或列表中的 nodes.line。
#1544: 当表格单元格为空时,
make text生成错误的表格。#1522: LaTeX 中表格的脚注显示两次。此问题自 Sphinx 1.2.1 的 #949 以来一直存在。
#508: 当从 setup.py 命令调用时,Sphinx 每次都以零退出。例如,
python setup.py build_sphinx -b doctest即使 doctest 失败也返回零。
版本 1.2.2(发布于 2014 年 3 月 2 日)¶
修复的 Bug¶
PR#211: 检查
html_logo文件是否存在时,检查完整相对路径而不是基本名称。PR#212: 修复 autodoc 和没有文档字符串的
__init__方法导致的 traceback。PR#213: 修复 setup 命令中缺少的导入。
#1357: 现在,
option文档化的选项名称再次允许不以破折号或斜杠开头,并且引用它们将正常工作。#1358: 使用“通配符”样式引用时,修复源目录外部图像路径的处理。
#1374: 修复 autosummary 在第一行没有句号结尾时生成过长摘要的问题。
#1383: 修复 sphinx-apidoc 的 Python 2.5 兼容性。
#1391: 实际阻止在 sphinx-quickstart 中同时使用“pngmath”和“mathjax”扩展。
#1386: 修复阻止通过入口点机制添加多个主题的错误。
#1370: 在文本编写器中忽略“toctree”节点,而不是引发异常。
#1364: 修复当存在“.. todolist::”指令时“make gettext”失败的问题。
#1367: 修复 PR#96 的一项更改,该更改破坏了 sphinx.util.docfields.Field.make_field 接口/行为中
item参数的使用。
文档¶
扩展了有关构建扩展的文档。
版本 1.2.1(发布于 2014 年 1 月 19 日)¶
修复的 Bug¶
#1335: 修复带有感叹号前缀(如
{% extends "!autosummary/class.rst" %})的 autosummary 模板重载导致无限递归函数调用。这是由 PR#181 引起的。#1337: 修复 autodoc 在
autoclass_content="both"的情况下使用无用的object.__init__文档字符串,当类没有__init__时。这是由 #1138 的一项更改引起的。#1340: 无法在语言='ja'生成的 HTML 快速搜索中搜索字母词。
#1319: 如果
html_logo文件不存在,则不崩溃。#603: 不使用 HTML 化的标题构建搜索索引(这导致标题中包含字面量的每个页面都找到“literal”)。
#751: 通过使用 longtable 允许 LaTeX 中的生产列表长度超过一页。
#764: 在 JS 搜索中始终以小写形式查找停用词。
#814: autodoc: 防止没有
__bases__的奇怪类型对象。#932: autodoc: 如果
__doc__不是字符串,则不崩溃。#933: 如果
option值格式不正确(包含空格但没有选项名称),则不崩溃。#908: 在 Python 3 中,正确处理 pngmath 扩展中 LaTeX 的错误消息。
#943: 在 autosummary 中,如果“第一句”包含大写字母,则识别它们以从文档字符串中提取。
#923: 在缓存 pngmath 生成的图像时,考虑整个 LaTeX 文档。这在
pngmath_latex_preamble更改时正确重建它们。#901: 当使用 Docutils 的新“math”标记而没有激活 Sphinx 数学扩展时,发出警告。
#845: 在代码块中,如果选定的词法分析器失败,即使已配置,也显示行号。
#929: 在 LaTeX 输出中正确支持解析后的字面块。
#949: 更新 Sphinx 附带的 tabulary.sty。
#1050: 将匿名标签添加到
objects.inv,以便通过intersphinx引用。#1095: 修复“scrolls”主题中始终包含打印媒体样式表的问题。
#1085: 修复当类描述设置了
:noindex:时当前类名未设置的问题。#1181: 更优雅地报告 autodoc 指令中的选项错误。
#1155: 修复在 Python 3 中自动记录 C 定义方法作为属性的问题。
#1233: 允许在 intersphinx 中使用“class”和“exc”角色查找 Python 类和异常。
#1198: 允许将“image”用于 figure 指令的“figwidth”选项,如 docutils 文档所示。
#1152: 通过包含 Python 2 和 3 的两个语法版本,并加载适用于运行的 Python 版本的版本,修复 Python 3 代码的 pycode 解析错误。
#1017: 当
option的参数不符合所需格式时,提供帮助并告知用户。#1345: 修复
nitpick_ignore的两个错误;现在您无需删除存储环境即可使更改生效。#1072: 在 JS 搜索中,通过在词干提取之前将单词小写来修复搜索大写单词的问题。
#1299: 使
math指令的行为更一致,并避免在 LaTeX 输出中生成空环境。#1308: 在将“raw”节点的内容馈送到搜索索引器之前,从中剥离 HTML 标签。
#1249: 修复手动文档的 LaTeX 页码重复问题。
#1292: 在链接检查器中,当被 HTTP 405 拒绝时,重试 HEAD 请求。还使重定向代码显而易见,并稍微调整输出以使其更清晰。
#1285: 避免 C 域对象和节标题之间的名称冲突。
#848: 使用
sphinx.ext.viewcode扩展在增量重建中始终采用最新的代码。#979, #1266: 修复
sphinx-apidoc中的排除处理。#1302: 修复
sphinx.ext.inheritance_diagram中在记录无法 pickle 的类时导致的回归。#1316: 从 epub 主题中删除硬编码的
font-face资源。#1329: 修复 .po 文件中翻译 msgstr 为空时导致的 traceback。
#1300: 修复在某些情况下翻译文档中的引用不起作用的问题。
#1283: 修复检测更改文件中的错误,该错误会尝试访问已删除文档的 doctree。
#1330: 修复
exclude_patterns在html_static_path中子目录的行为。#1323: 修复 HTML 编写器中发出空
<ul>标签的问题,这不符合有效的 HTML。#1147: 不在“singlehtml”构建器中发出侧边栏搜索框。
文档¶
#1325: 添加了“Intersphinx”教程部分。(
doc/tutorial.rst)
版本 1.2(发布于 2013 年 12 月 10 日)¶
新增功能¶
添加了
sphinx.version_info元组,用于以编程方式检查 Sphinx 版本。
不兼容的变更¶
删除了
sphinx.ext.refcounting扩展 – 它非常特定于 CPython,不应在主发行版中。
修复的 Bug¶
恢复 versionadded/changed 和 deprecated 指令的
versionmodifiedCSS 类。PR#181: 修复
html_theme_path = ['.']始终触发所有文档重建的问题(此更改保留了当前“主题更改导致重建”功能)。#1296: 修复默认区域设置下生成的 HTML 帮助 HTML 文件中的无效字符集。
PR#190: 修复 gettext 不提取其他块内的图标题和标题。感谢 Michael Schlenker。
PR#176: 确保 setup_command 测试始终可以导入 Sphinx。感谢 Dmitry Shachnev。
#1311: 修复 test_linkcode.test_html 在 C 区域设置和 Python 3 下失败的问题。
#1269: 修复 Python 3.2 或更高版本中的 ResourceWarnings。
#1138: 修复:当
autodoc_docstring_signature = True且autoclass_content = 'init'或'both'时,__init__ 行应从类文档中移除。
版本 1.2 beta3(发布于 2013 年 10 月 3 日)¶
新增功能¶
Sphinx 错误日志文件现在将包含已加载扩展的列表,以帮助调试。
不兼容的更改¶
PR#154: 移除 LaTeX 类名中的“sphinx”前缀,除了“sphinxmanual”和“sphinxhowto”。现在您可以不带“sphinx”前缀使用自定义文档类。感谢 Erik B。
已修复的错误¶
#1265: 修复 i18n:翻译从命名目标指向的节名称时崩溃。
一个错误的条件破坏了通常是 index.rst 的第一页上的搜索功能。此问题在 1.2b1 中引入。
#703: 当 Sphinx 无法解码带有非 ASCII 字符的文件名时,Sphinx 现在会捕获 UnicodeError,如果可能则继续执行,而不是引发异常。
版本 1.2 beta2(发布于 2013 年 9 月 17 日)¶
新增功能¶
apidoc现在默认忽略“_private”模块,并有一个选项-P来包含它们。apidoc现在有一个选项可以不为包和模块生成标题,以防模块文档字符串已包含 reST 标题。PR#161:
apidoc现在可以将每个模块写入一个独立页面,而不是将包中的所有模块组合到一个页面上。构建器:当目录更新时重建 i18n 目标文档。
HTML 编写器支持 docutils.conf 的“writers”和“html4css1 writer”部分。latex、manpage 和 texinfo 编写器也支持各自的“writers”部分。
新的
html_extra_path配置值允许指定应直接复制到 HTML 输出目录的文件目录。模块数据和属性的 Autodoc 指令现在支持
annotation选项,以便可以覆盖数据/属性值的默认显示。PR#136: Autodoc 指令现在支持
imported-members选项,以包含从不同模块导入的成员。新区域设置:马其顿语、僧伽罗语、印度尼西亚语。
使用 setuptools 插件机制进行主题包收集。
不兼容更改¶
PR#144, #1182: 强制 POT-Creation-Date 的时区偏移量为 LocalTimeZone,该日期由 gettext 构建器生成。感谢 masklinn 和 Jakub Wilk。
修复的错误¶
PR#132: jQuery 版本更新至 1.8.3。
PR#141, #982: 避免在使用 Python 3 写入 PNG 文件时崩溃。感谢 Marcin Wojdyr。
PR#145: 在并行构建中,Sphinx 丢弃第二个要写入的文档文件。感谢 tychoish。
PR#151: LaTeX 中表格的一些样式更新。
PR#153: 现在可以覆盖“extensions”配置值。
PR#155: 添加了对某些 C++11 函数限定符的支持。
修复:当模板包含 utf-8 编码字符串时,‘make gettext’导致 UnicodeDecodeError。
#828: 使用 inspect.getfullargspec() 能够在 Python 3 上文档化带仅关键字参数的函数。
#1090: 修复 i18n:同一行中的多个交叉引用(术语、引用、文档)返回相同的链接。
#1157: ‘globaltoc.html’ 和隐藏的 toctree 的组合导致异常。
#1159: 修复 Python 模块对象库存生成错误,并在 intersphinx 中添加一个解决方法,以修复受影响库存的处理。
#1160: 引文目标缺失导致 AssertionError。
#1162, PR#139: singlehtml 构建器没有将图像复制到 _images/。
#1173: 调整 setup.py 依赖项,因为 Jinja2 2.7 停止兼容 Python < 3.3 和 Python < 2.6。感谢 Alexander Dupuy。
#1185: 当 Python 模块声明错误或没有声明编码,并且包含非 ASCII 字符时,不要崩溃。
#1188: 如果“Project version”包含非 ASCII 字符,sphinx-quickstart 会引发 UnicodeEncodeError。
#1189: 在 quickstart 中使用全角字符作为“Project name”时,会给出“Title underline is too short”警告。
#1190: 在 quickstart 中使用非 ASCII 字符作为“Project name”时,输出的 TeX/texinfo/man 文件名没有基本名称(只有扩展名)。
#1192: 修复 manpage 编写器中超链接的转义问题。
#1193: 修复 i18n:同一行中的多个链接引用返回相同的链接。
#1176: 修复 i18n:自动编号的命名脚注和自动符号脚注缺少脚注引用编号。
PR#146,#1172: 修复并行构建中的 ZeroDivisionError。感谢 tychoish。
#1204: 修复生成指向本地 intersphinx 目标的链接错误。
#1206: 修复 i18n:gettext 未翻译告诫指令的标题。
#1232: Sphinx 在 Windows 上生成了损坏的 ePub 文件。
#1259: 在发出事件时保护调试输出调用;以防止任意对象的 repr() 实现导致构建失败。
#1142: 修复 Mac OS X 上 rst 文件名的 NFC/NFD 规范化问题。
#1234: 忽略仅包含空格字符的字符串。
版本 1.2 beta1(发布于 2013 年 3 月 31 日)¶
不兼容的更改¶
删除了自 1.0 版本以来已弃用的
sphinx.util.compat.directive_dwim()和sphinx.roles.xfileref_role()。PR#122:
latex_additional_files中给出的文件现在会覆盖 Sphinx 包含的 TeX 文件,例如sphinx.sty。PR#124:
versionadded、versionchanged和deprecated指令生成的节点现在包含所有添加的标记(例如“New in version X”)作为子节点,并且编写器不必生成额外的文本。PR#99:
seealso指令现在生成告诫节点而不是自定义seealso节点。
新增功能¶
标记
toctree指令的toctree()模板函数现在有一个includehidden选项,该选项包含隐藏的 toctree 条目(错误 #790 和 #1047)。toctree()模板函数的maxdepth选项中的一个错误已修复(错误 #1046)。PR#99: 将 seealso 指令简化为普通告诫。这移除了它们不寻常的 CSS 类 (admonition-see-also)、不一致的 LaTeX 告诫标题(“See Also”而不是“See also”)以及文本构建器中多余的缩进。
HTML 构建器
#783: 如果图像按宽度或高度缩放,则创建指向全尺寸图像的链接。
#1067: 改进 JavaScript 搜索结果的排序:标题中的匹配项排在全文匹配项之前,并且对象结果的分类更佳。还实现了可插拔的搜索评分器。
#1053: “rightsidebar”和“collapsiblesidebar”HTML 主题选项现在可以协同工作。
更新至 jQuery 1.7.1 和 Underscore.js 1.3.1。
Texinfo 构建器
当没有条目时,不再添加“Index”节点。
如果“deffn”类别包含大写字母,则不再将其大写。
desc_annotation节点现在已渲染。strong和emphasis节点现在像literal一样格式化。这样做的原因是标准的 Texinfo 标记(*strong*和_emphasis_)由于通常用于文档参数名称,导致输出混乱。字段列表格式已调整,以更好地显示“信息字段列表”。
system_message和problematic节点现在以与文本构建器类似的方式格式化。选项指令签名中不再执行连字符的“en-dash”和“em-dash”转换。
交叉引用现在使用
@ref代替@pxref,这可以防止在链接前添加“see”一词(不影响 Info 输出)。已添加
@finalout命令以获得更好的 TeX 输出。transition节点现在使用下划线(“_”)而不是星号(“*”)格式化。paragraphindent的默认值已从 2 更改为 0,这意味着段落默认不再缩进。#1110: 添加了一个新的配置值
texinfo_no_detailmenu,用于控制是否在“Top”节点的菜单中添加@detailmenu。除了“Top”节点,不再创建详细菜单。
修复了重复的域索引导致无效输出的问题。
LaTeX 构建器
PR#115: 在
latex_elements中添加'transition'项,用于自定义转换的显示方式。感谢 Jeff Klukas。PR#114: LaTeX 编写器现在默认包含“cmap”包。
'cmappkg'项在latex_elements中可用于控制此项。感谢 Dmitry Shachnev。当
language使用西里尔字母时,latex_elements中的'fontpkg'项现在默认为''。由 Dmitry Shachnev 建议。如果未在
conf.py中明确设置,则latex_documents、texinfo_documents和man_pages配置值将根据master_doc设置为默认值。以前,如果这些值未设置,则其各自的构建器不会生成任何输出。
国际化
为自定义模板添加 i18n 功能。例如:当使用
make gettext时,doc 目录中的 Sphinx 参考文档提供了一个sphinx.pot文件,其中包含来自doc/_templates/*.html的消息字符串。PR#61,#703: 添加了对非 ASCII 文件名处理的支持。
其他构建器
添加了 Docutils 原生 XML 和伪 XML 构建器。请参阅
XMLBuilder和PseudoXMLBuilder。PR#45: linkcheck 构建器现在检查
#anchor是否存在。PR#123, #1106: 添加
epub_use_index配置值。如果提供,它将用于 epub 构建器,而不是html_use_index。PR#126: 添加
epub_tocscope配置值。此设置控制 epub toc 的生成。用户现在还可以包含隐藏的 toc 条目。PR#112: 添加
epub_show_urls配置值。
扩展
PR#52:
special_members标志对 autodoc 的行为现在类似于members。PR#47: 添加了
sphinx.ext.linkcode扩展。PR#25: 在继承图中,类文档字符串的第一行现在是类的工具提示。
命令行接口
PR#75: 为 sphinx-apidoc 添加了
--follow-links选项。#869: sphinx-build 现在有一个选项
-T,用于在未处理的异常后打印完整的 traceback。sphinx-build 现在支持标准的
--help和--version选项。当使用无效选项或参数调用 sphinx-build 时,现在提供更具体的错误消息。
sphinx-build 现在有一个详细选项
-v,可以重复使用以获得更大的效果。一次出现提供比正常情况稍微详细的输出。两次或更多次出现此选项提供更详细的输出,可能对调试有用。
区域设置
PR#74: 修复了一些俄语翻译。
PR#54: 添加了挪威语博克马尔语翻译。
PR#35: 添加了斯洛伐克语翻译。
PR#28: 添加了匈牙利语翻译。
#1113: 添加希伯来语区域设置。
#1097: 添加巴斯克语区域设置。
#1037: 修复波兰语翻译中的拼写错误。感谢 Jakub Wilk。
#1012: 更新爱沙尼亚语翻译。
优化
通过缓存词干提取例程的结果来加快搜索索引的构建。在构建 Python 文档时节省了大约 20 秒。
PR#108: 添加了对并行构建的实验性支持,并带有一个新的
sphinx-build -j选项。
文档¶
PR#88: 添加了“Sphinx 开发者指南”(
doc/devguide.rst),其中概述了 Sphinx 项目的基本开发过程。添加了详细的“安装 Sphinx”文档(
doc/install.rst)。
修复的错误¶
PR#124: 修复 versionmodified 中没有悬空段落时忽略段落的问题。修复错误的 html 输出(嵌套的
<p>标签)。修复 versionmodified 无法翻译的问题。感谢 Nozomu Kaneko。PR#111: 即使设置了 inherited-members,也要遵守 add_autodoc_attrgetter()。感谢 A. Jesse Jiryu Davis。
PR#97: 修复翻译文档中的脚注处理。
修复文本编写器未处理 figure 指令内容的 visit_legend。
修复文本构建器不尊重宽/全角字符:标题下划线宽度、表格布局宽度和文本换行宽度。
修复 LaTeX 表头单元格中的前导空格。
#1132: 修复 LaTeX 表格输出中第一列多行单元格的问题。
#1128: 修复在非标准区域设置下尝试格式化时间字符串时出现的 Unicode 错误。
#1127: 修复 autodoc 尝试标记非 Python 文件时出现的 traceback。
#1126: 修复 LaTeX 中在错误位置(如命令行选项名称)将双连字符转换为 en-dash 的问题。
#1123: 允许
literalinclude给定的文件名中包含空格。#1120: 增加了对 Sphinx 内置主题“basic”、“haiku”和“scrolls”的 i18n 改进。感谢 Leonardo J. Caballero G。
#1118: 更新了西班牙语翻译。感谢 Leonardo J. Caballero G。
#1117: 在 sphinx-apidoc 中处理 .pyx 文件。
#1112: 避免当从文档中以不同方式(绝对/相对)引用时,下载文件重复。
#1111: 修复当
html_search_language为“ja”时搜索大写单词失败的问题。感谢 Tomo Saito。#1108: 文本编写器现在使用非默认起始值正确编号枚举列表(基于 Ewan Edwards 的补丁)。
#1102: 支持 autodoc 中的多上下文“with”语句。
#1090: 修复 gettext 未提取词汇表术语的问题。
#1074: 将环境版本信息添加到生成的搜索索引中,以避免与旧构建的兼容性问题。
#1070: 避免在 Python 3 运行时和保存的环境是在 Python 2 下创建时出现反序列化问题。
#1069: 修复了当 autodoc 尝试格式化没有关键字参数的“partial”函数签名时导致的错误(Artur Gaspar 的补丁)。
#1062: sphinx.ext.autodoc 使用 __init__ 方法签名作为类签名。
#1055: 修复带源目录相对路径的 web support。
#1043: 修复 sphinx-quickstart 再次询问是/否问题的问题,因为
input()在 Python 3.2.0 + Windows 上返回带额外“r”的值。感谢 Régis Décamps。#1041: 修复 cpp 域解析器无法解析带有修饰符的 const 类型。
#1038: 修复 cpp 域解析器无法解析 C++11 “static constexpr”声明。感谢 Jakub Wilk。
#1029: 修复当映射在 Python 3.3 中设置了复数键/值时 intersphinx_mapping 值不稳定。
#1028: 修复文本构建器中的行块输出。
#1024: 改进 Makefile/make.bat 错误消息,如果找不到 Sphinx。感谢 Anatoly Techtonik。
#1018: 修复文本构建器中的“container”指令处理。
#1015: 停止在 JavaScript 中覆盖 jQuery contains()。
#1010: 默认情况下使 pngmath 图像透明;IE7+ 应该能够处理它。
#1008: 修复 Python 3.3 的测试失败。
#995: 修复 LaTeX “howto”类的目录和页码。
#976: 修复 gettext 未提取索引条目。
PR#72: #975: 修复 Docutils 0.10 之前 gettext 未提取定义术语的问题。
#961: 修复代码片段中三引号的 LaTeX 输出。
#958: 在构建失败后不保留
environment.pickle。#955: 修复 i18n 转换。
#940: 修复 gettext 未提取图标题。
#920: 修复 PIL 打包问题,该问题允许在没有 PIL 命名空间的情况下导入
Image。感谢 Marc Schlaich。#723: 修复基于 WebKit 的浏览器中本地文件上的搜索功能。
#440: 修复某些文件系统中粗略的时间戳分辨率,导致过时文件列表错误。