Sphinx 1.8

Release 1.8.6 (released Nov 18, 2021)

依赖

  • #9807: Restrict Docutils to 0.17.x or older

版本1.8.5（发布于2019年3月10日）

Bug 修复

  • LaTeX：删除PDF标题页上作者姓名后的多余空格（参考：#6004）

  • #6026：LaTeX：与定义列表的交叉引用不起作用

  • #6046：LaTeX：在给出无效 Latex_elements 时，引发“TypeError”。

  • #6067：LaTeX：具有目标的图像被连接到下一行

  • #6067：LaTeX：在指定时，有目标未对齐。

  • #6149：LaTeX：标题中的 :index: 角色导致了 Use of \@icentercr doesn't match its definition 在 Latexpdf 创建时崩溃

  • #6019：imgconverter：存在多页PDF失败

  • #6047：autodoc:“autofunction”对方法对象发出警告

  • #6028：graphviz：确保 graphviz 文件名是可复制的

  • #6068：doctest：“skipif”选项可能会从文档中删除代码块

  • #6136：“:name:”选项用于“math”指令，导致崩溃

  • #6139：intersphinx：失败报告时的值错误

  • #6135：变更：只要找到任何模块均可修复 UnboundLocalError

  • #3859：册页：代码块标题未正确显示

版本1.8.4（2019年2月3日发布）

Bug 修复

  • #3707：Latex：无粗体复选标记(✔) 可用。

  • #5605：当文档语言设置为中文时，无法搜索英语单词。

  • #5889：LaTeX：用户“numfig_format”被删除空间，可能导致生成失败

  • C++，修复涉及到东方 cv-qualifiers 声明的超链接。

  • #5755：C++，修复函数模板中的重复声明错误，其中返回类型中有约束。

  • C++，解析一元右折叠表达式和二进制折叠表达式。

  • Pycode 无法处理 Windows 上的 egg 文件

  • #5928：KeyError：运行生成时出现 “DOCUTILSCONFIG”

  • #5936：LaTeX：PDF 生成因在警告中包含高于页面高度的图像而中断

  • #5231：“makehtml” 不在 “locale” 目录中读取和生成 “po” 文件

  • #5954：“:scale:” 如果图像出现了警告，图像选项可能会破坏 PDF 构建

  • #5966：mathjax 尚未加载到增量生成上

  • #5960：LaTeX：2018年9月以来修改的 PDF 布局 TeXLive 更新 parskip.sty

  • #5948：LaTeX：为节生成重复的标签

  • #5958：Versionadded 指令导致 Python 3.5.0崩溃

  • #5995：autodoc：autodoc_mock_导入与 Python3.7 上的元类冲突

  • #5871：texinfo：不允许节标题中出现 “.”

版本1.8.3（2018年12月26日发布）

新增特性

  • LaTeX：可以插入自定义材料显示在标题页的背面，请参见 “maketitle” 的讨论 latex_elements （仅限 “手册”` docclass）

Bug 修复

  • #5725：mathjax：默认情况下对“最新”版本使用 CDN URL

  • #5460：html 搜索不适用于某些第三方主题

  • #5520：LaTeX，说明包不兼容 Sphinx 1.6

  • #5614：autodoc：当导入内置模块时，增量构建被破坏

  • #5627：qt 帮助： index.htmlQTIN 帮助丢失

  • #5659：linkcheck：包含多字节字符的超链接崩溃

  • #5754：DOC：修正以下错误 LaTeX个性化

  • #5810：LaTeX：从 1.6.6 开始，sphinxVerbatim需要显式的“hllines”设置（参考：#1238）

  • #5636：C++，固定浮点文字解析。

  • #5496（又）：C++，用重复的部分构建修复声明。

  • #5724：快速启动：当 $LCu ALL 为空时，Sphinx 快速启动失败

  • #1956：默认 conf.py 并不遵从 PEP8

  • #5849：LaTeX：文档类 “maketitle” 被重写，无法使用原始含义代替 Sphinx 自定义的含义

  • #5834：apidoc：“--tocfile” 帮助错误

  • #5800：Todo：如果在 TextElement 中定义了 Todo，则崩溃

  • #5846：htmlhelp：将 .hhc/.hhk 文件中的十六进制转义转换为十进制转义

  • htmlhelp：breaked.hhk 文件在标题包含双引号时生成

版本1.8.2（2018年11月11日发布）

不兼容的变更

  • #5497：不包括 MathJax.js 以及 jsmath.js 除非真的需要。

新增特性

  • #5471：显示适当的弃用警告

Bug 修复

  • #5490：Latex：枚举列表使用重新标记导致崩溃

  • #5492：sphinx build 无法生成使用 Python<3.5.2 的文档

  • #3704：Latex：带有图例的图形的“标签”位置错误

  • #5496：C++，当一个符号被声明两次以上时，修复声明。

  • #5493：gettext：因模板损坏而崩溃

  • #5495：包含文件中带有文档选项的 csv table 指令被破坏（参考：#4821）

  • #5498：autodoc：找不到 “functools.partial”

  • #5480：autodoc：找不到不可解析的前向引用的类型提示

  • #5419：生成了不兼容的 math_block 节点

  • #5548：修复已存在文件的 ensuredir()

  • #5549：graphviz： 正确的处理了不存在的路径

  • #3002：i18n：引用同一脚注的多个脚注引用导致 node_ids 重复

  • #5563：Latex：由插件生成的 footnote_references 引发了 LaTeX 生成器崩溃

  • #5561：所有 pdf 在旧版本 xindy 中失效

  • #5557：quickstart：不接受未被批处理的文件

  • #3080：texinfo：多行准则已损坏

  • #3080：texinfo：多行引用已断开

版本1.8.1（2018年9月22日发布）

不兼容的变更

  • LaTeX“%pagestyle”命令已移动到 LaTeX 模板。PDF 中没有任何更改，除非包含这些内容的 “sphinxtableofcontents” 已在以下文件中自定义：配置文件. （参考：#5455）

Bug 修复

  • #5418：Sphinx 内部版本 -d/doctrees 文件的默认路径错误

  • #5421: autodoc emits deprecation warning for autodoc_default_flags

  • #5422: lambda 对象导致存储环境出现 PicklingError

  • #5417: 在 Python 2.7.5 中 Sphinx 无法创建带有语法错误的文件

  • #4911：为 make.bat 新增 latexpdf 以适用于无 make-mode 情况

  • #5436：Autodoc 不使用具有属性/方法的枚举子类

  • #5437：autodoc：在导入 eggs 模块上崩溃

  • #5433：Latex：ImportError: 无法导入名为 DEFAULT_SETTINGS” 的模块

  • #5431：autodoc：“autofunction” 省略了可召回对象的警告

  • #5457：修复了对重写时错误消息中的类型错误的禁用

  • #5453：“howto”文档的 PDF 版本没有页码

  • #5463：mathbase：math_role 和 MathDirective 在 1.8.0 中未出现

  • #5454：Latex：日语文档的 PDF 索引已消失

  • #5432：Py 域：“:type:” 字段无法处理 “:term:” 引用

  • #5426：Py 域：类属性引发 TypeError

1.8.0版（2018年9月13日发布）

依赖

1.8.0b1

  • LaTeX：latex_use_xindy，如果 True （默认为 xelatex/lualatex），则指示“make latexpdf”使用 xindy 作为常规索引。确保你的 LaTeX 分发包括它。（参考：5134）

  • LaTeX：在 Windows 上的 “make latexpdf” 需要 “latexmk”

不兼容的变更

1.8.0b2

  • #5282：html 主题：优先引用 html 主题的 “pygmentsu-style” 设置

  • 下载文件的 URL 已更改

  • #5127：quickstart：如果 “Makefile” 和 “make.bat” 已存在，这不会被重写

1.8.0b1

  • #5156: the sphinx.ext.graphviz extension runs dot in the directory of the document being built instead of in the root directory of the documentation.

  • #4460：将任何数据存储到环境的扩展应将其 env 数据结构的版本作为元数据返回。具体请参见 扩展的元数据。

  • Sphinx 期望源解析器模块支持的文件格式为 “Parser.supported” 属性

  • epub_author 、 epub_publisher 的默认值已从 “unknown”切换至 author。这与 sphinx-build 生成的 “conf.py” 文件保持一致。

  • 将 “document.settings” 对象的 gettext_compact 属性移除。 请使用“config.gettext_compact”。

  • 读取阶段的处理顺序已更改。智能引号、sphinx域、 doctree-read 事件和版本控制 doctree 的调用时间比目前更早。有关详细信息，请阅读以下描述 Sphinx.add_transform()

  • #4827：在阅读模式中所有 “substitution_definition” 节点都从 doctree 中被移除

  • 在 “$HOME” 和 “/etc” 中 “docutils.conf” 将忽略目录。只有“confdir” 的 “docutils.conf” 服从。

  • #789：“:samp:” 用于转义带反斜杠的大括号的角色支持

  • #4811：从源文件中排除 html_static_path 下的文件。

  • Latex：使用 “sphinxcite”用作引用而非 “hyperref”

  • The config value viewcode_import is renamed to viewcode_follow_imported_members (refs: #4035)

  • #1857：Latex: latex_show_pagerefs 未给页面引用添加引述

  • #4648：Latex：现在 “rubric” 元素呈现为无编号的节标题

  • #4983：html：productionlist 标记的定位点已更改

  • 现在允许在模板中修改模板变量 “script_files”。请使用 “app.add_js_file()”。

  • #5072：只保存新文档的环境对象

  • #5035：qthelp 生成器允许 qthelp_namespace 中出现破折号

  • LaTeX：对于 lualatex 或 xelatex，默认情况下使用 xindy 作为 UTF-8 的可替换项 makeindex （参考：#5134）。升级 Sphinx 后，请在新建之前清理现有项目的 Latex 建造储备库。

  • #5163：html：hlist 项现在对齐到顶部

  • “highlightlang” 指令用于处理段落

  • #4000：LaTeX：模板已更改。以下元素已移动到其中：

    • “begin{document}”

    • “shorthandoff” 变量

    • “maketitle” 变量

    • “tableofcontents” 变量

已弃用

1.8.0b2

  • 不推荐 “sphinx.io.SphinxI18nReader.set_lineno_for_reporter()”

  • 不推荐使用 “sphinx.io.SphinxI18nReader.line”

  • “sphinx.util.i18n.find_catalog_source_file()” 已更改；不推荐使用 gettext_compact 参数

  • #5403：“sphinx.util.images.guess_mimetype()” 已更改；不推荐使用 content 参数

1.8.0b1

  • source_parsers is deprecated

  • autodoc_default_flags is deprecated

  • quickstart：“--epub”选项现成为默认选项，因而不推荐使用

  • Drop function based directive support. For now, Sphinx only supports class based directives (see Directive)

  • 不推荐 “sphinx.util.docutils.directive_helper()”

  • 不推荐 “sphinx.cmdline”

  • 不推荐 “sphinx.make_mode”

  • 不推荐 “sphinx.locale.l_()”

  • #2157：不推荐使用 HTML 主题的“warn()” 帮助功能

  • app.override_domain() is deprecated

  • 不建议使用 app.add_stylesheet()

  • 不建议使用 app.add_javascript()

  • 不建议使用 app.import_object()

  • app.add_source_parser() 已被修改，不建议使用 suffix 参数

  • 不建议使用 sphinx.versioning.prepare()

  • Config.__init__() 已被修改，不建议使用 dirname, filename 和 tags 参数

  • 不建议使用 Config.check_types()

  • 不建议使用 Config.check_unicode()

  • 不建议使用 sphinx.application.CONFIG_FILENAME

  • 不建议使用 highlightlang 指令

  • 不建议使用 BuildEnvironment.load()

  • 不建议使用 BuildEnvironment.loads()

  • 不建议使用 BuildEnvironment.frompickle()

  • 不建议使用 env.read_doc()

  • 不建议使用 env.update()

  • 不建议使用 env._read_serial()

  • 不建议使用 env._read_parallel()

  • 不建议使用 env.write_doctree()

  • 不建议使用 env._nitpick_ignore

  • 不推荐使用 “env.versionchanges”

  • 不推荐使用 “env.dump()”

  • 不建议使用 “env.dumps()”

  • 不建议使用 “env.topickle()”

  • 不建议使用 “env.note_versionchange()”

  • 不推荐使用 “sphinx.writers.latex.Table.caption_footnotetexts”

  • 不推荐使用 “sphinx.writers.latex.Table.header_footnotetexts”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.footnotestack”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.in_container_literal_block”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.next_section_ids”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.restrict_footnote()”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.check_latex_elements()”

  • 不推荐使用 “sphinx.writers.latex.LaTeXTranslator.bibitems”

  • sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated

  • 不推荐使用 “sphinx.writers.latex.ExtBabel.get_shorthandoff()

  • 不推荐使用 “sphinx.writers.html.HTMLTranslator.highlightlang”

  • 不推荐使用 “sphinx.writers.html.HTMLTranslator.highlightlang_base”

  • 不推荐使用 “sphinx.writers.html.HTMLTranslator.highlightlangopts”

  • 不推荐使用 “sphinx.writers.html.HTMLTranslator.highlightlinenothreshold”

  • sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated

  • sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated

  • sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated

  • sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is deprecated

  • 不建议使用 “sphinx.ext.mathbase”

  • 不建议使用 “sphinx.ext.mathbase.math”

  • 不推荐使用 “sphinx.ext.mathbase.displaymath”

  • 不建议使用 “sphinx.ext.mathbase.eqref”

  • 不推荐使用 “sphinx.ext.mathbase.is_in_section_title()”

  • sphinx.ext.mathbase.MathDomain is deprecated

  • 不建议使用 “sphinx.ext.mathbase.MathDirective”

  • 不建议使用 “sphinx.ext.mathbase.math_role”

  • 不推荐使用 “sphinx.ext.mathbase.setup_math()”

  • 不推荐使用 “sphinx.directives.other.VersionChanges”

  • 不推荐使用 “sphinx.highlighting.PygmentsBridge.unhighlight()”

  • sphinx.ext.mathbase.get_node_equation_number() is deprecated

  • 不推荐使用 “sphinx.ext.mathbase.wrap_displaymath()”

  • 不推荐使用 “sphinx.highlighting.PygmentsBridge” 的 “trim_doctest_flags” 参数

有关更多详细信息，请参见 deprecation APIs list。

新增特性

1.8.0b2

  • #5388：确保冻结的对象描述是可复制的

  • #5362：apidoc: 给 ToC 新增 “--tocfile” 选项以更改文件名

1.8.0b1

  • 新增 config-inited 事件

  • 新增 “sphinx.config.Any” 以代表配置值接受任何类型的值

  • source_suffix 允许将映射文件扩展到文件类型

  • 新增 author 作为配置值。

  • #2852：imgconverter：支持 GIF 向 PNG 转换

  • “sphinx-build” 命令支持 i18n 控制台输出

  • 新增 “app.add_message_catalog()” 和“sphinx.locale.get_translations()” 以支持第三方插件

  • 新增 HTML 主题的“warn()” 帮助功能

  • 添加 “Domain.enumerable_nodes”来管理本域可枚举节点（实验中）

  • 为 “override”新增关键词参数以应用 API

  • LaTeX：新键 “fvset” 用于 latex_elements。对于 XeLaTeX/LuaLaTeX，它的默认设置是 “fanvyvrb”，在代码块中使用普通的、不小的字体大小（参考：#4793）

  • 新增 html_css_files 和 epub_css_files 以从配置文件汇总增加 CSS 文件

  • 新增 html_js_files 以为配置增加 JS 文件

  • #4834：确保集合对象描述是可重复的。

  • #4828：允许部分重写 numfig_format。不需要完整的定义。

  • 改进包括时的警告信息（参考：#4818）

  • LaTeX：可单独定制 guilabel 和 menuselection （参考：4830）

  • 新增 “Config.read()” 类方法从配置文件创建新的配置对象

  • #4866：将 graphviz 图用“<div>” 标签包裹

  • viewcode：新增 viewcode-find-source 和 viewcode-follow-imported 以无需加载的载入源码

  • #4785：napoleon：将字符串添加到翻译文件以进行本地化

  • #4927：向高亮指令的 linenothreshold 选项传递无效值时显示警告

  • C++：

    • 新增“cpp:texpr” 角色作为 “cpp:expr`”子角色。

    • 新增对并集的支持。

    • #3593, #2683：：新增对使用以“@”开头的名称的匿名实体的支持。

    • #5147：新增对（大多数）字符字面值的支持。

    • 现支持主模板中的交叉引用实体的，并能正确地将其记录。

    • #1552：为添加新的交叉引用格式 “cpp:any” 及 “cpp:func” 角色，用于引用特定的函数重载。

  • #3606：MathJax 应该加载 async 属性

  • html: 输出 “canonical_url” 元数据，若 html_baseurl 置位（参考：#4193）

  • #5029：autosummary：向template 暴露 inherited_members

  • #3784：mathjax：增加 mathjax_options 为脚本标记提供选项

  • #726, #969：新增 mathjax_config t 为 mathjax 提供在线配置

  • #4362：Latex：如果文件未被修改，则不要覆写.tex文件

  • #1431：Latex： 添加字母数字枚举列表支持

  • 新增 latex_use_xindy 用于 UTF-8 savvy 索引，如果 latex_engine 引擎是 “xelatex” 或 “lualatex” 则默认为 “True”。（参考：#5134, #5192, #5212）

  • #4976：“SphinxLoggerAdapter.info()” 现支持 “location” 参数

  • #5122：setuptools：支持 nitpicky 的选项

  • #2820：autoclass 指令支持内嵌类

  • 新增 “app.add_html_math_renderer()” 以注册 HTML 渲染器

  • Apply trim_doctest_flags 到所有构建器（参见文本、手册页）

  • #5140：linkcheck：向 HTTP 客户端添加更好的 Accept 头部

  • #4614：sphinx-build： 新增 “--keep-going” 选项以显示所有的警告

  • 新增：math:numref 角色以涉及等式（与 eq 同）

  • quickstart：epub 生成器 默认开启

  • #5246：新增 singlehtml_sidebars 来为单个 HTML 生成器配置边栏

  • #5273：doctest：有条件的跳过 doctest

  • #5306：autodoc：对无效的类型提示发出警告

  • #4075, #5215：autodoc：新增 autodoc_default_options 以将选项值按字典接受

Bug 修复

1.8.0b2

  • html：如果滚动，搜索框将覆盖到其他元素

  • i18n：翻译目录的警告有错误的行号（参考：#5321）

  • #5325：Latex：交叉引用被多重标记的对象破坏

  • C++，用于符号添加和查找。查找不应再在部分生成中中断。详见：#5337。

  • #5348：未显示对远程文件的下载引用

  • #5282: html theme: “pygments_style“ 在默认情况下被 “conf.py” 重写

  • #4379：toctree 在排除文档时显示令人困惑的警告

  • #2401：autodoc：“:members:” 引发 “:special-members:” 未显示

  • autodoc：ImportError 被 AttributeError 替换为更深层的模块

  • #2720，#4034:“:download:”、重复名称和并行生成的链接不正确

  • #5290：autodoc：无法分析 egg 包中的源代码

  • #5399：如果存在 po 文件，则 Sphinx 将会崩溃

1.8.0b1

  • i18n：每次初始化时都会重置消息目录

  • #4850：Latex：脚注内的脚注未呈现

  • #4945:i18n:修复IndexBuilder的 lang_COUNTRY 不正确回退。感谢 Shengjing Zhu。

  • #4983：productionlist 指令为令牌生成无效的 ID

  • #5132: lualatex：如果索引词以 Unicode 字符开头，则 PDF 生成失败

  • #5133: Latex：索引标题“符号”和“数字”没有国际化

  • #5114: sphinx-build: 处理扫描文档时的错误

  • epub：当“自我”列在目录树上时，脊柱已经断了（参考：#4611）

  • #344：autosummary无法理解模块级属性的docstring

  • #5191: C++，防止函数中嵌套的声明，以避免查找问题。

  • #5126: C++，为某些模板参数类型添加缺少的 ISPACK 方法。

  • #5187：C++，同时也声明声明器的属性。

  • C++，解析删除表达式和基本的新表达式。

  • #5002：graphviz：SVG无法适应列宽

移除特性

1.8.0b1

  • “sphinx.ext.pngmath” 扩展

文档

1.8.0b1

  • #5083：国际化中 make.bat 选项修复错误。

  • #5115: napoleon：新增在文档中添加＃4613添加的警告。