Sphinx 1.5

版本 1.5.6（发布于 2017 年 5 月 15 日）

修复的错误

  • #3614: Sphinx 在 requests-2.5.0 下崩溃

  • #3618: autodoc 在使用元组参数时崩溃

  • #3664: Sphinx生成的LaTeX列表项后没有空格

  • #3657: 如果存在以 genindex 开头的文档,EPUB 构建器会崩溃

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

  • #3685: 使用第三方域时出现AttributeError

  • #3702: LaTeX 编写器以硬编码的 \small 样式化图例

  • #3708: LaTeX 编写器允许 irc 方案

  • #3717: 停止强制要求 favicon 必须是 .ico 格式

  • #3731, #3732: 保护 isenumclass 谓词不受非类参数的影响

  • #3320: 关于容器类型无法找到引用目标的警告

  • Makefile 中用于 latex 构建目录的 ARCHIVEPREFIX 拼写错误

发布版本 1.5.5 (发布于 2017年4月3日)

修复的错误

  • #3597: python 域在给定无效名称时引发 UnboundLocalError

  • #3599: 移动到新的 MathJax CDN

发布 1.5.4（发行于 2017 年 4 月 2 日）

添加的特性

  • #3470: 使 genindex 支持所有类型的字母,而不仅限于拉丁字母

修复的错误

  • #3445: 将 'inputenc' 键设置为 \usepackage[utf8x]{inputenc} 导致 PDF 构建失败

  • EPUB 文件在 content.opf 中有重复的 nav.xhtml 链接,除了第一次构建之外

  • #3488: 当 release 或 version 包含返回代码时,objects.inv 已损坏

  • #2073, #3443, #3490: gettext 构建器,除非内容相同且没有创建日期,否则将写入 pot 文件.感谢 Yoshiki Shibukawa.

  • #3487: intersphinx: 无法引用选项

  • #3496: LaTeX longtable的最后一列可能会比其内容宽得多

  • #3507: 生产列表指令的 LaTeX 输出中的错误引号

  • #3533: 从 Sphinx 1.3.1 升级到 1.5.3 会导致以代码形式渲染的链接的 LaTeX 编译失败

  • #2665, #2607: 在C++文档字段中链接名称,并使其他领域也可以使用.

  • #3542: C++,修复非类型模板参数与模板的解析错误.

  • #3065, #3520: python 域无法识别嵌套类

  • #3575: 在使用Sphinx构建的土耳其文档中,pdflatex的问题再次出现（参考 #2997, #2397）

  • #3577: 修复intersphinx调试工具

  • 在:confval:latex_documents 的标题项中插入 \large 这样的LaTeX命令会导致PDF构建失败（参考 #3551, #3567）

发布 1.5.3（发布日期:2017年2月26日）

添加的特性

  • 支持请求-2.0.0（实验性）（参考:#3367）

  • (latex) PDF页面边距尺寸可以自定义（参考:#3387）

  • literalinclude directive allows combination of :pyobject: and :lines: options (refs: #3416)

  • #3400: make-mode在构建文档时不使用子进程

修复的错误

  • #3370: 代码块的标题未被提取进行翻译

  • LaTeX: release 没有被转义 (参考: #3362)

  • #3364: sphinx-quickstart 提示在宽度为80字符的控制台上溢出

  • 自1.5版以来,PDF的目录和书签中缺少一般索引的条目（参考:#3383）

  • #3392:'releasename' 在 latex_elements 中不起作用

  • #3356: 日文 'manual' 文档类的页面布局文本区域更短

  • #3394:当 'pointsize' 不是 10pt 时,日文 'manual' 文档生成错误的 PDF 页面尺寸

  • #3399: 快速入门: conf.py未被模板覆盖

  • #3366: option 指令不允许标点符号

  • #3410: release 中的返回代码破坏了HTML搜索

  • #3427: autodoc: Windows上的内存地址未被剥离

  • #3428: xetex 构建测试由于 fontspec v2.6 定义 \strong 失败

  • #3349: IndexBuilder.load() 的结果是错误的

  • #3450: EPUB 文档中出现 &nbsp

  • #3418: 搜索按钮在自然主题和金字塔主题中未对齐

  • #3421: 无法翻译表的标题

  • #3552: linkcheck 引发 UnboundLocalError

版本 1.5.2（发布于 2017 年 1 月 22 日）

不兼容的更改

  • 依赖要求更新:requests 2.4.0 或更高版本（参考: #3268, #3310）

添加的特性

  • #3241:如果存在缺陷的titlesec,则发出latex警告（参考 #3210）

  • #3194: 参考 $MAKE 环境变量以确定 make 命令

  • 为嵌套的编号toctree发出警告（参考:#3142）

  • #978:intersphinx_mapping 还允许将列表作为参数

  • #3340: (LaTeX) parsed-literal 中的长行会像:rst:dir:code-block 一样换行,内联数学和脚注完全正常.

修复的错误

  • #3246: xapian 搜索适配器崩溃

  • #3253: 在Py2环境中,使用无标题的toctree构建另一个区域时会产生 None 标题

  • #185: 包含原始节点的章节标题引用已损坏

  • #3255: 在Py3.4环境中,autodoc无法正确支持Enum类属性的文档.

  • #3261:latex_use_parts 导致 Sphinx 崩溃

  • 警告类型 misc.highlighting_failure 不起作用

  • #3294:add_latex_package() 使非LaTeX构建器崩溃

  • 表格的标题被渲染为无效的HTML（参考:#3287）

  • #3268: Sphinx 在 Debian jessie 上使用 requests 包时崩溃

  • #3284: Sphinx在使用引发不可序列化异常的扩展进行并行构建时崩溃

  • #3315: 使用文档类’memoir’时,引用文献在latex构建中崩溃

  • #3328: 无法隐式引用标题

  • #3329: 如果 po 文件无效且无法读取,则发出警告.同时写入 mo

  • #3337: 定义列表术语的分类器渲染丑陋

  • #3335: gettext无法提取field_list中字段的field_name

  • #2952: C++,修复对operator()函数的引用.

  • 修复 code-block 和解析的 LaTeX 输出中的 Unicode 上标和下标数字问题 (参考 #3342)

  • LaTeX 写入器:在解析的字面量中保留 " 字符不变（参考 #3341）

  • #3234: intersphinx 对编码清单失败

  • #3158: PDF 输出中标题后空格过多

  • #3317: 如果带有连字符,解析文字内容中的 URL 在 PDF 中被错误渲染

  • 当通过替代插入的解析文字中的图像文件名包含连字符时,LaTeX会崩溃（参考＃3340）

  • 在解析文字中的插入脚注的LaTeX渲染错误（参考 #3340）

  • 在解析文字中,内联数学公式无法被LaTeX很好地渲染（参考 #3340）

  • #3308:在pdf构建器中解析的字面量不会换行很长的行（参考 #3340）

  • #3295: 无法导入扩展 sphinx.builders.linkcheck

  • #3285: autosummary: 星号被转义了两次

  • LaTeX,为日本文档传递dvipdfm选项给geometry包（参考#3363）

  • 修复 parselinenos() 无法解析左半开区间 (参见 “-4”)

发布 1.5.1 （于 2016 年 12 月 13 日发布）

添加的特性

  • #3214:允许使用 suppress_warnings 来抑制来自 epub 构建器的 “未知 mimetype” 警告.

修复的错误

  • #3195: 无法并行构建

  • #3198:当toctree包含’self’时引发AttributeError

  • #3211: 删除未翻译的Sphinx区域设置目录（已由未翻译的it_IT覆盖）

  • #3212: HTML 构建器与 Docutils 0.13 崩溃

  • #3207: 与解析文字指令（ \DUrole ）内部引用相关的更多LaTeX问题

  • #3205: sphinx.util.requests 在旧版 pyOpenSSL (< 0.14) 上崩溃

  • #3220: 当有重复引用时发生 KeyError

  • #3200: LaTeX: 不允许在 desc_name 中使用 xref

  • #3228:build_sphinx 命令在缺少依赖时崩溃

  • #2469: 忽略gettext构建器的目录文件更新.感谢Hiroshi Ohkubo.

  • #3183: 在生成的索引页面中随机化跳转框的顺序.

发布 1.5（发布于 2016 年 12 月 5 日）

不兼容的更改

1.5a1

  • latex,fancybox包不再是sphinx.sty的依赖项

  • 使用 'locales' 作为 locale_dirs 的默认值

  • latex,ifthen包不再是sphinx.sty的依赖项

  • latex,样式文件不修改fancyvrb的Verbatim（也可作为OriginalVerbatim使用）,而是使用sphinxVerbatim作为自定义包装的名称.

  • latex,软件包 newfloat 不再被使用（且不再包含）（参考 #2660;自 1.3.4 起开始使用,并从 1.4 起与 Sphinx 一起发布）.

  • latex,表格中的文字块不使用OriginalVerbatim,而是使用sphinxVerbatimintable,它可以处理标题并自动换行（参考#2704）.

  • latex,若在图像的 width 或 height 属性中发现 pt ,则替换为 TeX 等效的 bp .

  • latex,如果图像的 width 或 height 属性未指定单位,则使用 px 而不是忽略它.

  • latex: 将pygments的分离样式表放入独立的.sty文件中

  • #2454: sourcelink的文件名现在已更改. html_sourcelink_suffix 的值将附加到原始文件名（如 index.rst.txt ）.

  • sphinx.util.copy_static_entry() is now deprecated. Use sphinx.util.fileutil.copy_asset() instead.

  • sphinx.util.osutil.filecopy() skips copying if the file has not been changed (ref: #2510, #2753)

  • 在更新jQuery版本从1.11.0到3.1.0后,已停止对Internet Explorer 6-8、Opera 12.1x或Safari 5.1+的支持（参考: #2634, #2773）

  • QtHelpBuilder 不生成搜索页面 (参考: #2352)

  • QtHelpBuilder使用 nonav 主题代替默认主题,以提高可读性.

  • latex: 为了给日文文档提供良好的默认设置,Sphinx在:confval:language 为 ja 时使用 jreport 和 jsbook 作为文档类.

  • sphinx-quickstart now allows a project version is empty

  • 修复:在epub/qthelp构建器上处理 :download: 角色.它们忽略该角色,因为不支持它.

  • sphinx.ext.viewcode doesn’t work on epub building by default. viewcode_enable_epub option

  • sphinx.ext.viewcode disabled on singlehtml builder.

  • 默认使用 sphinx-quickstart 的 make-mode.要禁用此模式,请使用 -M 选项

  • 修复 genindex.html ,Sphinx 的文档模板,链接地址指向自身以满足 xhtml 标准.

  • 默认使用epub3构建器.旧的epub构建器已重命名为epub2.

  • 修复 epub 和 epub3 构建器,即使 epub_use_index = False 也包含指向 genindex 的链接.

  • html_translator_class is now deprecated. Use set_translator() API instead.

  • 放弃对Python 2.6和3.3的支持

  • 删除 epub3 构建器的 epub3_page_progression_direction 选项（使用 epub3_writing_mode ）.

  • #2877: 将 latex_elements['footer'] 重命名为 latex_elements['atendofbody']

1.5a2

  • #2983: 将 epub3_description 和 epub3_contributor 重命名为 epub_description 和 epub_contributor .

  • 删除 themes/basic/defindex.html;不再使用

  • Sphinx不再附带（但仍使用）LaTeX样式文件 fncychap

  • #2435: 精简快速入门的 conf.py

  • The sphinx.sty latex package does not load itself “hyperref”, as this is done later in the preamble of the latex output via 'hyperref' key.

  • Sphinx不再提供自定义修改的LaTeX样式文件 tabulary .使用的是未修改的包.

  • #3057: 默认情况下,latex PDF 输出中的脚注标记前不再留空格, \sphinxBeforeFootnote 允许用户在需要时自定义.

  • LaTeX目标要求包 hyperref 的选项 hyperfootnotes 保持为默认值（即 true ）不变（参考:#3022）

1.5最终版

  • #2986:themes/basic/defindex.html 现已弃用

  • 默认情况下,发出将在 Sphinx 1.6 中被弃用的警告.用户可以通过设置环境变量 PYTHONWARNINGS 来改变这种行为.请参考 弃用警告 .

  • #2454: 新增 JavaScript 变量 SOURCELINK_SUFFIX

过时

这些功能在 Sphinx 1.6 中已被移除:

  • i18n 功能中的 LDML 格式支持

  • sphinx.addnodes.termsep

  • 在 sphinx.util.pycompat 中的一些函数和类: zip_longest 、 product 、 all 、 any 、 next 、 open 、 class_types 、 base_exception 、 relpath 、 StringIO 、 BytesIO .请使用标准库版本

如果显示任何弃用警告,例如 RemovedInSphinxXXXWarning ,请参阅 弃用警告 .

添加的特性

1.5a1

  • #2951: 为 apidoc 添加 --implicit-namespaces PEP-0420 支持.

  • 为sphinx.ext.inheritance_diagram添加 :caption: 选项.

  • #2471:添加用于默认 doctest 标志的配置变量.

  • 将linkcheck构建器转换为requests,以便更好地处理编码

  • #2463, #2516: 将”meta”指令的关键字添加到搜索索引

  • :maxdepth: option of toctree affects secnumdepth (ref: #2547)

  • #2575: 现在 sphinx.ext.graphviz 允许 :align: 选项

  • 如果指定了未知的键,显示警告给 latex_elements

  • 如果没有域与 primary_domain 匹配,则显示警告 (参考: #2001)

  • C++,当角色类型对其所指的目标类型造成误导时显示警告（例如,将 class 角色用于函数）.

  • latex,writer 将更多的文本样式抽象为可自定义的宏,例如 visit_emphasis 将输出 \sphinxstyleemphasis 而不是 \emph （这可能在其他地方使用或在添加的 LaTeX 包中使用）.请参阅 sphinx.sty 末尾的列表（参考: #2686）.

  • latex,供笔记、警告和其他告诫类型使用的环境和参数的公共名称,允许通过 'preamble' 键或输入文件实现完全自定义（参考:功能请求 #2674, #2685）

  • latex,更好地计算了一些表格的列宽（因此,表格现在正确填充了行宽,因此将会有轻微的变化;参考:#2708）

  • latex,sphinxVerbatim 环境更容易自定义（参考:#2704）.除了已经存在的 VerbatimColor 和 VerbatimBorderColor:

    • 两个长度 \sphinxverbatimsep 和 \sphinxverbatimborder ,

    • 布尔值 \ifsphinxverbatimwithframe 和 \ifsphinxverbatimwrapslines .

  • latex,表格内的文字块标题已处理,长代码行已换行以适合表格单元格（参考:#2704）

  • #2597: 将警告消息显示为深红色

  • latex,允许使用px单位设置图像尺寸（默认是96px=1in）

  • 遇到无效的维度单位时显示警告

  • #2650: 在 setup.py 命令中添加 --pdb 选项

  • latex,允许自定义代码列表的 \small 使用（参见 #2721）

  • #2663: 为setup.py命令添加 --warning-is-error 选项

  • 如果使用了已弃用的latex选项,显示警告

  • 添加 sphinx.config.ENUM 以检查配置值是否在候选项中

  • math: 为HTML输出中的每个方程添加超链接标记

  • 添加新主题 nonav ,该主题不包含任何导航链接.此主题适用于任何帮助生成器,例如 qthelp.

  • #2680:sphinx.ext.todo 现在在启用 todo_emit_warnings 时会发出警告.此外,它还会发出一个名为 todo-defined 的额外事件,以处理第三方扩展中的 TODO 条目.

  • Python 域签名解析器现在为 ‘exceptions’ 使用了 xref mixin,这样异常类可以自动链接.

  • #2513: 添加 latex_engine 以通过conf.py切换LaTeX引擎

  • #2682: C++,基本支持属性（C++11风格和GNU风格）.新配置变量 ‘cpp_id_attributes’ 和 ‘cpp_paren_attributes’ 可用于引入自定义属性.

  • #1958: C++,添加配置变量 ‘cpp_index_common_prefix’ 用于去除 C++ 对象索引文本中的前缀.

  • C++,添加了概念指令.感谢 mickk-on-cpp.

  • C++,增加了对模板介绍语法的支持.感谢 mickk-on-cpp.

  • #2725: LaTeX构建器:允许使用用户定义的模板文件（实验性）

  • apidoc现在通过不写入内容不变的文件来避免使缓存文件失效.如果频繁运行apidoc,这可以带来显著的性能提升.

  • #2851:sphinx.ext.math 如果找不到方程,则发出缺失引用事件

  • #1210:eqref 角色现在支持交叉引用

  • #2892: 为 sphinx-apidoc 添加了 -a ( --append-syspath ) 选项

  • #1604: epub3 构建器:在 iBooks 中查看时遵循与字体相关的 CSS.

  • #646:option 指令支持将 ‘.’ 字符作为选项的一部分

  • 添加关于 kindlegen 的文档,并修复其文档结构.

  • #2474: 为 sphinx.ext.intersphinx 添加 intersphinx_timeout 选项

  • #2926: EPUB3 构建器支持纵向模式 ( epub3_writing_mode 选项)

  • #2695:build_sphinx 子命令对于 setuptools 处理异常与 sphinx-build 一致

  • #326:numref 角色也可以引用章节

  • #2916:numref 角色也可以将标题作为其链接文本

1.5a2

  • #3008:linkcheck 构建器忽略自签名证书 URL

  • #3020: 新增 'geometry' 键到 latex_elements ,其默认使用 LaTeX 样式文件 geometry.sty 来设置页面布局

  • #2843: 为literalinclude指令添加:start-at:和:end-at:选项

  • #2527: 为 toctree 指令添加 :reversed: 选项

  • 为 sphinx-quickstart 添加 -t 和 -d 选项,以支持生成的 Sphinx 项目的模板.

  • #3028: 将 {path} 和 {basename} 添加到 figure_language_filename 的格式中

  • 新的 'hyperref' 键在 latex_elements 字典中 (参见 #3030)

  • #3022: 允许在脚注中使用代码块以便生成LaTeX PDF输出

1.5b1

  • #2513: 为XeLaTeX提供更好的默认设置

  • #3096:'maxlistdepth' 密钥用于解决 LaTeX 列表限制

  • #3060: autodoc 支持 Enum 类属性的文档说明.现在 autodoc 只渲染 Enum 属性的值,而不是 Enum 属性的表示形式.

  • >> 添加 --extensions 到 sphinx-quickstart 以支持从命令行启用任意扩展 (参考: #2904)

  • #3104, #3122:'sphinxsetup' 用于 Sphinx LaTeX 的 key=value 样式

  • #3071: Autodoc: 允许模拟模块装饰器不改变地传递函数

  • #2495: linkcheck: 允许使用 linkcheck_anchors_ignore 跳过锚点检查

  • #3083: 让Unicode不换行空格像LaTeX的 ~ 一样作用（修复 #3019）

  • #3116: 允许在PDF输出中对内联文字进行换行（参考 #3110）

  • #930: sphinx-apidoc 允许使用通配符排除路径.感谢 Nick Coghlan.

  • #3121: 添加 inlineliteralwraps 选项以控制在 LaTeX 中的行内文字是否换行

1.5最终版

  • #3095: 添加 tls_verify 和 tls_cacerts 以支持 linkcheck 和 intersphinx 中自签名的 HTTPS 服务器

  • #2215: sphinx-quickstart 生成的 make.bat 可以从其他目录调用.感谢 Timotheus Kampik.

  • #3185:添加新的警告类型 misc.highlighting_failure

修复的错误

1.5a1

  • #2707: (latex) 表格的列宽计算不当

  • #2799: 导入sphinx模块时,Sphinx会自动安装角色和指令.现在Sphinx在运行应用时安装它们.

  • sphinx.ext.autodoc crashes if target code imports * from mock modules by autodoc_mock_imports.

  • #1953:Sphinx.add_node 不会添加由 html_translator_class 安装的翻译器处理程序

  • #1797: 文本生成器在顶部插入空行

  • #2894: quickstart main() 不使用 argv 参数

  • #2874: gettext构建器无法提取 only 指令下的所有文本

  • #2485: autosummary 在多个 source_suffix 值下崩溃

  • #1734: 无法翻译 toctree 指令的标题

  • 无法翻译meta指令的内容（引用:#1734）

  • #2550: 外部链接在帮助查看器中打开

  • #2687: 多次运行 Sphinx 会产生 ‘已注册’ 警告

1.5a2

  • #2810: 意大利文档中pdflatex的问题

  • 使用 latex_elements.papersize 来指定 Makefile 中 LaTeX 的纸张大小

  • #2988: 链接检查:如果拒绝HEAD请求,使用GET请求重试

  • #2990: 如果启用 linkcheck_anchors,linkcheck 会引发 “无法隐式将 ‘bytes’ 对象转换为 str” 错误

  • #3004: 使用了无效的链接类型 “top” 和 “up”

  • #3009: 自 Sphinx 1.4.4 起,LaTeX 中解析字面量的渲染错误

  • #3000:option 指令生成无效的 HTML 锚点

  • #2984: 如果启用了 html_split_index ,将生成无效的 HTML

  • #2986: themes/basic/defindex.html 应更改为支持 HTML5

  • #2987: 如果多个ID分配给列表,则生成了无效的HTML

  • #2891: HTML搜索无法提供所有结果

  • #1986: PDF输出中的标题

  • #147: LaTeX章节样式的问题

  • #3018: LaTeX 关于页面布局尺寸和章节标题的问题

  • 修复 LaTeX 样式文件中 \pysigline 的问题（参见 #3023）

  • #3038:sphinx.ext.math* 如果标签重复则抛出 TypeError

  • #3031: 与 LaTeX 包 tocloft 不兼容

  • #3003: LaTeX不支持脚注中的文本块

  • #3047:PDF输出中脚注前的间距不一致,且允许断裂

  • #3045: HTML搜索索引创建器应忽略”原始”内容（如果现在是HTML）

  • #3039: 英文词干提取器在单词首字母大写时返回错误的单词

  • 修复 make-mode Makefile 模板 (参见 #3056, #2936)

1.5b1

  • #2432: 修复 varargs 和仅关键字参数之间不需要的 *.感谢 Alex Grönholm.

  • #3062: 使用1.5a2构建PDF失败（自PR#3030以来,对于日文文档未定义 \hypersetup ）

  • 更好的多行签名在HTML中的呈现.

  • #777: LaTeX 输出”嵌套过深”（参考 #3096）

  • 让LaTeX图像包含遵循 scale 优先于文本宽度适配（参考 #2865,#3059）

  • #3019:LaTeX在描述带参数的C函数时失败（参考#3083）

  • 修复 LaTeX 内联文字中的 < > - 吞噬空格的问题

1.5最终版

  • #3069: 即使 'babel' 键设置为空字符串,LaTeX 输出仍包含一个 \addto\captions...

  • #3123: 用户 'babel' 键设置不再被遵循

  • #3155: 修复 html_sourcelink_suffix 在 IE 和 Opera 中失效的 JavaScript

  • #3085: 在构建文档失败后保持当前目录.感谢 Timotheus Kampik.

  • #3181: pLaTeX 在包含短破折号的节时崩溃

  • #3180: latex: 在连续的单行或多行cpp签名之间添加拉伸/收缩 (参见 #3072)

  • #3128: globing images不支持.svgz文件

  • #3015: 修复Windows上的一个坏测试.

  • #1843: 修复自定义元类的描述符类文档.感谢Erik Bray.

  • #3190: util.split_docinfo 无法解析多行字段主体

  • #3024, #3037: 在Python3中,当日志消息无法编码为控制台编码时,application.Sphinx._log崩溃.

测试

  • 为了简化,Sphinx使用外部mock包,即使 unittest.mock 存在.