Sphinx 1.5¶
发布 1.5.6 (发布于 2017 年 5 月 15 日)¶
修复的 Bug¶
#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 日)¶
修复的 Bug¶
#3597：如果给出无效名称，python 域会引发 UnboundLocalError
#3599：迁移到新的 MathJax CDN
发布 1.5.4 (发布于 2017 年 4 月 2 日)¶
新增功能¶
#3470：使 genindex 支持所有类型的字母，而不仅仅是拉丁字母
修复的 Bug¶
#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：productionlist 指令的 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 调试工具
LaTeX 命令，例如
\\large插入到latex_documents的标题项中会导致 PDF 构建失败（参考 #3551, #3567）
发布 1.5.3 (发布于 2017 年 2 月 26 日)¶
新增功能¶
支持 requests-2.0.0 (实验性) (参考: #3367)
(latex) PDF 页面边距尺寸可自定义 (参考: #3387)
literalinclude指令允许组合:pyobject:和:lines:选项 (参考: #3416)#3400：make-mode 在构建文档时未使用 subprocess
修复的 Bug¶
#3370：code-block 的标题未被翻译
LaTeX:
release未转义 (参考: #3362)#3364：sphinx-quickstart 在 80 字符宽度的控制台上提示溢出
自 1.5 以来，PDF 的 TOC 和书签缺少总索引的条目 (参考: #3383)
#3392：
latex_elements中的'releasename'未生效#3356：日语
'manual'文档类的页面布局文本区域较短#3394：当
'pointsize'不是10pt时，日语'manual'文档的 PDF 页面尺寸错误#3399：quickstart: conf.py 未被模板覆盖
#3366：option 指令不允许标点符号
#3410：
release中的返回码破坏了 html 搜索#3427：autodoc：Windows 上未去除内存地址
#3428：由于 fontspec v2.6 定义了
\strong，xetex 构建测试失败#3349：
IndexBuilder.load()的结果已损坏#3450：EPUB 文档中出现了  
#3418：nature 和 pyramid 主题中搜索按钮错位
#3421：无法翻译表格的标题
#3552：linkcheck 引发 UnboundLocalError
发布 1.5.2 (发布于 2017 年 1 月 22 日)¶
不兼容的变更¶
依赖要求更新：requests 2.4.0 或更高版本 (参考: #3268, #3310)
新增功能¶
#3241：如果 titlesec 有 bug 则发出 latex 警告 (参考 #3210)
#3194：引用 $MAKE 环境变量以确定
make命令为嵌套的带编号 toctree 发出警告 (参考: #3142)
#978：
intersphinx_mapping也允许列表作为参数#3340：(LaTeX) parsed-literal 中的长行会像
code-block一样换行，内联数学和脚注功能齐全。
修复的 Bug¶
#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：使用 docclass ‘memoir’ 进行 latex 构建时，参考文献崩溃
#3328：无法隐式引用 rubric
#3329：如果 po 文件无效且无法读取，则发出警告。也写入 mo
#3337：定义列表项的分类器渲染丑陋
#3335：gettext 不提取 field_list 中字段的 field_name
#2952：C++，修复对 operator() 函数的引用。
修复
code-block和 parsed-literal LaTeX 输出中 Unicode 上标和下标数字 (参考 #3342)LaTeX 写入器：将 parsed-literal 内的
"字符原样保留 (参考 #3341)#3234：intersphinx 对编码的清单失败
#3158：PDF 输出中标题后空间过多
#3317：parsed-literal 内容中的 URL 如果带连字符，在 PDF 中渲染错误
如果通过替换插入到 parsed-literal 中的图像文件名包含连字符，LaTeX 崩溃 (参考 #3340)
parsed-literal 中插入的脚注的 LaTeX 渲染错误 (参考 #3340)
parsed-literal 中的内联数学无法被 LaTeX 很好地渲染 (参考 #3340)
#3308：使用 pdf 生成器时，Parsed-literals 不会换行很长的行 (参考 #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：parsed-literal 指令内部引用的更多 latex 问题 (
\DUrole)#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，package fancybox 不再是 sphinx.sty 的依赖
使用
'locales'作为locale_dirs的默认值latex，package ifthen 不再是 sphinx.sty 的依赖
latex，样式文件不再修改 fancyvrb 的 Verbatim (也可用作 OriginalVerbatim)，而是使用 sphinxVerbatim 作为自定义包装器的名称。
latex，package 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()现已弃用。请改用sphinx.util.fileutil.copy_asset()。sphinx.util.osutil.filecopy()如果文件未更改则跳过复制 (参考: #2510, #2753)Internet Explorer 6-8、Opera 12.1x 或 Safari 5.1+ 的支持被取消，因为 jQuery 版本从 1.11.0 更新到 3.1.0 (参考: #2634, #2773)
QtHelpBuilder 不生成搜索页面 (参考: #2352)
QtHelpBuilder 使用
nonav主题而不是默认主题来提高可读性。latex：为了给日语文档提供良好的默认设置，如果
language为ja，Sphinx 会使用jreport和jsbook作为文档类。sphinx-quickstart现在允许项目版本为空修复 epub/qthelp 构建器上的 :download: 角色。它们忽略该角色，因为它们不支持它。
sphinx.ext.viewcode默认情况下在 epub 构建时不起作用。viewcode_enable_epub选项sphinx.ext.viewcode在 singlehtml 构建器上禁用。默认使用
sphinx-quickstart的 make-mode。要禁用此功能，请使用-M选项修复
genindex.html（Sphinx 的文档模板）的链接地址，使其满足 xhtml 标准。默认使用 epub3 生成器。旧的 epub 生成器重命名为 epub2。
修复
epub和epub3生成器，即使epub_use_index = False，它们也包含指向genindex的链接。html_translator_class现已弃用。请改用set_translator()API。放弃对 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
sphinx.stylatex 包不再自行加载“hyperref”，因为这将在 latex 输出的序言中通过'hyperref'键稍后完成。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.termsepsphinx.util.pycompat中的一些函数和类：zip_longest、product、all、any、next、open、class_types、base_exception、relpath、StringIO、BytesIO。请改用标准库版本；
如果显示任何弃用警告，例如 RemovedInSphinxXXXWarning，请参阅 弃用警告。
新增功能¶
1.5a1
#2951：为 apidoc 添加
--implicit-namespacesPEP-0420 支持。为 sphinx.ext.inheritance_diagram 添加
:caption:选项。#2471：为默认 doctest 标志添加配置变量。
将 linkcheck 生成器转换为 requests 以更好地处理编码
#2463, #2516：将 “meta” 指令的关键字添加到搜索索引
toctree 的
:maxdepth:选项影响secnumdepth(参考: #2547)#2575：现在
sphinx.ext.graphviz允许:align:选项如果
latex_elements指定了未知键，则显示警告如果没有域与
primary_domain匹配，则显示警告 (参考: #2001)C++，当角色类型与它引用的目标类型不一致时（例如，将
class角色用于函数），显示警告。latex，写入器将更多的文本样式抽象为可自定义的宏，例如
visit_emphasis将输出\sphinxstyleemphasis而不是\emph（可能在其他地方或在添加的 LaTeX 包中使用）。请参阅sphinx.sty末尾的列表 (参考: #2686)latex，用于 note、warning 和其他告诫类型的环境和参数的公共名称，允许通过
'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 以检查配置值是否在候选列表中
数学：在 HTML 输出中为每个方程添加超链接标记
添加新主题
nonav，不包含任何导航链接。这适用于任何帮助生成器，如 qthelp。#2680：如果
todo_emit_warnings启用，sphinx.ext.todo现在会发出警告。此外，它还发出一个名为todo-defined的额外事件，以处理第三方扩展中的 TODO 条目。Python 域签名解析器现在将 xref 混合器用于“exceptions”，允许异常类自动链接。
#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会发出 missing-reference 事件#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：setuptools 的
build_sphinx子命令与sphinx-build处理异常的方式相同#326：
numref角色也可以引用章节#2916：
numref角色也可以将标题作为其链接文本
1.5a2
#3008：
linkcheck生成器忽略自签名证书 URL#3020：
latex_elements字典中新增'geometry'键，其默认值使用 LaTeX 样式文件geometry.sty来设置页面布局#2843：为 literalinclude 指令添加 :start-at: 和 :end-at: 选项
#2527：为 toctree 指令添加
:reversed:选项为
sphinx-quickstart添加-t和-d选项，以支持模板化生成的 Sphinx 项目。#3028：将
{path}和{basename}添加到figure_language_filename的格式中latex_elements字典中新增'hyperref'键 (参考 #3030)#3022：允许 LaTeX PDF 输出中的脚注中使用代码块
1.5b1
#2513：XeLaTeX 的更好默认设置
#3096：
'maxlistdepth'键以解决 LaTeX 列表限制#3060：autodoc 支持 Enum 类属性的文档。现在 autodoc 只渲染 Enum 属性的值，而不是 Enum 属性的表示。
为
sphinx-quickstart添加--extensions，以支持从命令行启用任意扩展 (参考: #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) tabular 的列宽计算错误
#2799：Sphinx 在导入 sphinx 模块时自动安装角色和指令。现在 Sphinx 在运行应用程序时安装它们。
如果目标代码从模拟模块中 * 导入（通过
autodoc_mock_imports），sphinx.ext.autodoc会崩溃。#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：linkcheck：如果 HEAD 请求被拒绝，则使用 GET 请求重试
#2990：如果启用 linkcheck_anchors，linkcheck 会引发“无法隐式将 'bytes' 对象转换为 str”错误
#3004：使用了无效的链接类型“top”和“up”
#3009：自 Sphinx 1.4.4 以来，LaTeX 中 parsed-literals 的渲染效果不佳
#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：修复变长参数和仅关键字参数之间不必要的 *。感谢 Alex Grönholm。
#3062：使用 1.5a2 构建 PDF 失败 (自 PR#3030 以来，日语文档中
\hypersetup未定义)HTML 中多行签名的更好渲染。
#777：LaTeX 输出“嵌套太深” (参考 #3096)
让 LaTeX 图像包含在适应文本宽度之前遵守
scale(参考 #2865, #3059)#3019：带参数的 C 函数描述导致 LaTeX 失败 (参考 #3083)
修复 latex 内联字面值，其中
< > -吞噬了一个空格
1.5 最终版
#3069：即使
'babel'键设置为空字符串，LaTeX 输出仍包含一个\addto\captions...#3123：用户
'babel'键设置不再遵守#3155：修复
html_sourcelink_suffix的 JavaScript 在 IE 和 Opera 中失败的问题#3085：在中断构建文档后保持当前目录。感谢 Timotheus Kampik。
#3181：pLaTeX 在包含破折号的节中崩溃
#3180：latex：在连续的单行或多行 cpp 签名之间添加拉伸/收缩 (参考 #3072)
#3128：globing 图像不支持 .svgz 文件
#3015：修复 Windows 上的一个损坏测试。
#1843：修复具有自定义元类的描述符类的文档。感谢 Erik Bray。
#3190：util.split_docinfo 无法解析多行字段体
#3024, #3037：在 Python3 中，当日志消息无法编码为控制台编码时，application.Sphinx._log 崩溃。
测试¶
为简化起见，Sphinx 甚至在
unittest.mock存在时也使用外部 mock 包。