Sphinx 1.2

版本 1.2.3（发布于 2014 年 9 月 1 日）

添加的功能

  • #1518:sphinx-apidoc 命令现在增加了 --version 选项以显示版本信息并退出

  • 新地区:希伯来语,欧洲葡萄牙语,越南语.

修复的错误

  • #636: 在LaTeX构建中保持文字块中的直单引号.

  • #1419: 生成的 i18n sphinx.js 文件缺少来自 ‘.js_t’ 和 ‘.html’ 的消息目录条目.此问题自 Sphinx 1.1 开始出现

  • #1363: 修复国际化: 缺少与 currentmodule 指令或 currentclass 指令的 Python 域交叉引用.

  • #1444: autosummary 不从属性的文档字符串创建描述.

  • #1457:在python3环境中,当链接目标URL包含哈希部分时,执行linkcheck会导致 “无法隐式将’bites’对象转换为str” 的错误.感谢Jorge_C.

  • #1467: 如果指定了不存在的方法,Python3会抛出异常

  • #1441: autosummary 无法正确处理嵌套类.

  • #1499:在conf.py中使用不可调用的 setup 时,sphinx-build现在会发出用户友好的错误信息.

  • #1502: 在autodoc中,修复包含反斜杠的参数默认值的显示问题.

  • #1226: autodoc, autosummary: 导入 setup.py 通过 automodule 将触发设置过程并执行 sys.exit() .现在 Sphinx 避免了 SystemExit 异常,并发出警告而不会意外终止.

  • #1503: py:function 指令在指定默认参数为空列表 [] 时生成了不正确的签名.感谢 Geert Jansen.

  • #1508: 非ASCII文件名在生成singlehtml、latex、man、texinfo及更改时引发异常.

  • #1531: 在 Python3 环境中,docutils.conf 的一般部分设置 ‘source_link=true’ 会导致类型错误.

  • PR#270, #1533: 非ASCII文档字符串在与inheritance-diagram指令一起使用时会导致UnicodeDecodeError.感谢WAKAYAMA shirou.

  • PR#281, PR#282, #1509: TODO扩展与websupport不兼容.感谢Komiya Takeshi.

  • #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日）

修复的错误

  • PR#211: 在检查 html_logo 文件的存在性时,检查完整的相对路径,而不是仅仅检查文件名.

  • PR#212: 修复了在没有文档字符串的 __init__ 方法中使用autodoc时出现的回溯错误.

  • PR#213: 修复了安装命令中缺少的导入.

  • #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 日）

修复的错误

  • #1335:修复带有感叹号前缀的autosummary模板重载,如 {% extends "!autosummary/class.rst" %} 导致无限递归函数调用的问题.这是由PR#181引起的.

  • #1337: 修复 autoclass_content="both" 在类没有 __init__ 时使用无用的 object.__init__ 文档字符串的问题.该问题是由于 #1138 的更改引起的.

  • #1340: 无法在使用 language=’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: 在自动摘要中,如果首句包含大写字母,则识别”首句”以从文档字符串中提取.

  • #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: 允许在 figure 指令的 “figwidth” 选项中使用 “image”,如 docutils 所述.

  • #1152: 通过为Python 2和3包括两个语法版本,并加载适用于当前Python版本的版本,修复Python 3代码的pycode解析错误.

  • #1017: 请提供帮助,并在:rst:dir: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: 修复在文档中记录无法被pickle的类时, sphinx.ext.inheritance_diagram 的回归问题.

  • #1316: 从 epub 主题中移除硬编码的 font-face 资源.

  • #1329: 修复 .po 文件中空翻译 msgstr 的回溯问题.

  • #1300: 修复在某些情况下翻译文档中的引用无法工作的情况.

  • #1283: 修复了一个在检测更改文件时的错误,该错误会试图访问已删除文档的文档树.

  • #1330: 修复 html_static_path 中子目录的 exclude_patterns 行为.

  • #1323: 修复在HTML输出中发出空的 <ul> 标签,这不是有效的HTML.

  • #1147: 在 “singlehtml” 构建器中不发出侧边栏搜索框.

文档

  • #1325: 添加了”Intersphinx”教程部分. (doc/tutorial.rst )

发布 1.2 (发布于 2013年12月10日)

添加的功能

  • 添加了 sphinx.version_info 元组,以便程序化检查Sphinx版本.

不兼容变更

  • 移除了 sphinx.ext.refcounting 扩展 – 该扩展非常特定于 CPython,并不适合在主发行版中存在.

修复的错误

  • 恢复 versionmodified CSS 类以用于 versionadded/changed 和 deprecated 指令.

  • PR#181: 修复 html_theme_path = ['.'] 始终触发所有文档重建的问题（此更改保持了当前 “主题更改导致重建” 的功能）.

  • #1296: 修复生成默认语言环境的HTML帮助文件时无效的字符集问题.

  • PR#190:修复gettext无法提取其他块内部的图形标题和标题.感谢Michael Schlenker.

  • PR#176: 确保setup_command测试始终可以导入Sphinx.感谢Dmitry Shachnev.

  • #1311: 修复在C语言环境和Python 3下,test_linkcode.test_html失败的问题.

  • #1269: 修复Python 3.2或更高版本中的ResourceWarnings.

  • #1138: 修复:当 autodoc_docstring_signature = True 且 autoclass_content = 'init' 或 'both' 时,__init__行应从类文档中移除.

版本 1.2 beta3（发布于 2013 年 10 月 3 日）

添加的功能

  • Sphinx错误日志文件将现在包括一个已加载扩展的列表,以帮助调试.

不兼容变更

  • PR#154: 除’sphinxmanual’和’sphinxhowto’外,从LaTeX类名中移除了”sphinx”前缀.现在您可以使用自定义文档类而无需”sphinx”前缀.感谢Erik B.

修复的错误

  • #1265: 修复国际化: 当翻译从命名目标指向的章节名称时发生崩溃.

  • 一个错误的条件导致搜索功能在通常是index.rst的首页上失效.这个问题是在1.2b1中引入的.

  • #703: 当 Sphinx 无法解码包含非 ASCII 字符的文件名时,Sphinx 现在会捕获 UnicodeError,并在可能的情况下继续,而不是抛出异常.

发布 1.2 beta2（发布于2013年9月17日）

添加的功能

  • apidoc now ignores “_private” modules by default, and has an option -P to include them.

  • apidoc now has an option to not generate headings for packages and modules, for the case that the module docstring already includes a reST heading.

  • PR#161:apidoc 现在可以将每个模块写入一个独立的页面,而不是将包中的所有模块合并在一个页面上.

  • Builders: 当目录更新时,重建i18n目标文档.

  • 支持 docutils.conf 中的 ‘writers’ 以及 HTML writer 中的 ‘html4css1 writer’ 部分.latex、manpage 和 texinfo writer 也支持各自的 ‘writers’ 部分.

  • 新的 html_extra_path 配置值允许指定包含文件的目录,这些文件将直接复制到 HTML 输出目录.

  • 自动文档指令现在支持一个 annotation 选项,以便可以覆盖数据/属性值的默认显示.

  • PR#136: Autodoc 指令现在支持 imported-members 选项,以包含从不同模块导入的成员.

  • 新语言环境:马其顿语、僧伽罗语、印尼语.

  • 使用setuptools插件机制的主题包集合.

不兼容变更

  • PR#144, #1182:在gettext构建器生成的POT-Creation-Date上强制时区偏移为本地时区.感谢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: sphinx-quickstart 如果 “项目版本” 包含非ASCII字符,将引发 UnicodeEncodeError.

  • #1189: 当在快速启动中将全角字符用于 “项目名称 “时,出现警告 “标题下划线太短”.

  • #1190: 当在quickstart中使用非ASCII字符作为”项目名称”时,输出的TeX/texinfo/man文件名只有扩展名,缺少基本文件名.

  • #1192: 修复manpage编写器中超链接的转义问题.

  • #1193: 修复国际化: 同一行中的多个链接引用返回相同链接.

  • #1176: 修复国际化: 自动编号命名脚注和自动符号脚注缺少脚注引用编号.

  • PR#146,#1172: 修复并行构建中的 ZeroDivisionError.感谢 tychoish.

  • #1204: 修复错误生成指向本地 intersphinx 目标的链接.

  • #1206: 修复国际化: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 指令生成的节点现在包括所有添加的标记（如 “在版本 X 中新增”）作为子节点,作者不需要生成额外的文本.

  • PR#99: seealso 指令现在生成告示节点,而不是自定义的 seealso 节点.

添加的功能

  • 标记

    • The toctree directive and the toctree() template function now have an includehidden option that includes hidden toctree entries (bugs #790 and #1047). A bug in the maxdepth option for the toctree() template function has been fixed (bug #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 构建器

    • 当没有条目时,将不再添加”索引”节点.

    • “deffn” 类别如果包含大写字母,则不再以大写形式显示.

    • desc_annotation nodes are now rendered.

    • strong and emphasis nodes are now formatted like literals. The reason for this is because the standard Texinfo markup (*strong* and _emphasis_) resulted in confusing output due to the common usage of using these constructs for documenting parameter names.

    • 字段列表格式已调整,以更好地显示”信息字段列表”.

    • system_message and problematic nodes are now formatted in a similar fashion as done by the text builder.

    • 在选项指令签名中不再执行连字符的”en-dash”和”em-dash”转换.

    • @ref is now used instead of @pxref for cross-references which prevents the word “see” from being added before the link (does not affect the Info output).

    • 添加了 @finalout 命令以改善 TeX 输出.

    • transition nodes are now formatted using underscores (“_”) instead of asterisks (“*”).

    • The default value for the paragraphindent has been changed from 2 to 0 meaning that paragraphs are no longer indented by default.

    • #1110: 添加了一个新的配置值 texinfo_no_detailmenu 用于控制是否在 “Top” 节点的菜单中添加 @detailmenu .

    • 详细菜单不再创建,除了 “Top” 节点.

    • 修复了重复域索引导致无效输出的问题.

  • LaTeX 构建器:

    • PR#115: 在 latex_elements 中添加 'transition' 项,用于自定义过渡的显示方式.感谢Jeff Klukas.

    • PR#114:LaTeX 写入器现在默认包含 “cmap” 包.可以使用 latex_elements 中的 'cmappkg' 项来控制这一点.感谢 Dmitry Shachnev.

    • The 'fontpkg' item in latex_elements now defaults to '' when the language uses the Cyrillic script. Suggested by Dmitry Shachnev.

    • The latex_documents, texinfo_documents, and man_pages configuration values will be set to default values based on the master_doc if not explicitly set in conf.py. Previously, if these values were not set, no output would be generated by their respective builders.

  • 国际化:

    • 为自定义模板添加国际化功能.例如:在文档目录中的 Sphinx 参考文档提供了一个 sphinx.pot 文件,该文件包含来自 doc/_templates/*.html 的消息字符串,当使用 make gettext 时.

    • 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: 添加了 --follow-links 选项到 sphinx-apidoc.

    • #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 不可翻译的问题.感谢 Kaneko Nozomu.

  • PR#111: 在设置 inherited-members 时仍然尊重 add_autodoc_attrgetter().感谢 A. Jesse Jiryu Davis.

  • PR#97:修复翻译文档中的脚注处理.

  • 修复文本写入器未处理图形指令内容的 visit_legend.

  • 修复文本构建器不尊重宽字符/全角字符的问题:标题下划线宽度、表格布局宽度和文本换行宽度.

  • 修复LaTeX表头单元格中的前导空格.

  • #1132: 修复首列多行单元格的LaTeX表格输出.

  • #1128: 修复在使用非标准区域设置格式化时间字符串时出现的Unicode错误.

  • #1127:修复当autodoc尝试对非Python文件进行词法分析时的回溯错误.

  • #1126: 修复在错误位置（如LaTeX中的命令行选项名称）将双连字符转换为破折号的问题.

  • #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支持.

  • #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:如果找不到 Sphinx,改善 Makefile/make.bat 错误信息.感谢 Anatoly Techtonik.

  • #1018:修复文本构建器中 “container” 指令的处理.

  • #1015: 停止在JavaScript中重写jQuery的contains().

  • #1010: 默认使pngmath图像透明;IE7及更高版本应能处理.

  • #1008: 修复与Python 3.3的测试失败.

  • #995: 修复 LaTeX “howto” 类的目录和页码.

  • #976: 修复gettext未提取索引条目.

  • PR#72: #975: 修复 gettext 在 Docutils 0.10 之前未提取定义术语的问题.

  • #961:修复代码片段中三重引号的LaTeX输出.

  • #958: 在构建失败后,不保留 environment.pickle .

  • #955: 修复 i18n 转换.

  • #940: 修复gettext无法提取图表标题.

  • #920: 修复了PIL打包问题,使得可以在没有PIL命名空间的情况下导入 Image .感谢Marc Schlaich.

  • #723: 修复WebKit浏览器中本地文件的搜索功能.

  • #440: 修复某些文件系统中粗糙的时间戳分辨率,导致生成错误的过期文件列表.