Sphinx 1.8

发布 1.8.6（发布于 2021 年 11 月 18 日）

依赖关系

• #9807: 限制Docutils版本为0.17.x或更早

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

修复的错误

• 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: 報告失敗時的ValueError

• #6135: 更改:修复在找到任何模块时的 UnboundLocalError

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

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

修复的错误

• #3707: latex: 没有可用的粗体勾号 (✔).

• #5605: 将文档语言设置为中文时,无法搜索英文单词.

• #5889: LaTeX: 用户 numfig_format 中的空格被剥离,可能导致构建失败

• C++,修复涉及 east cv-qualifiers 的声明的超链接.

• #5755: C++,修复返回类型中具有约束的函数模板的重复声明错误.

• C++,解析一元右折叠表达式和二元折叠表达式.

• pycode无法在Windows上处理egg文件

• #5928: 构建时出现 KeyError: ‘DOCUTILSCONFIG’

• #5936: LaTeX: 由于在警告框中包含的图像高度超过页面高度,PDF构建破坏

• #5231: “make html” 不读取和构建 “locale” 目录中的 “po” 文件

• #5954::scale: 图片选项可能在警告框中使用时破坏 PDF 构建

• #5966: mathjax在增量构建中未加载

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

• #5948: LaTeX: 为章节生成了重复的标签

• #5958: versionadded 指令在 Python 3.5.0 中导致崩溃

• #5995: autodoc: autodoc_mock_imports 与 Python 3.7 上的元类冲突

• #5871: texinfo: 不允许使用段落标题 .

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

添加的功能

• LaTeX:可以插入自定义内容以显示在标题页的背面,请参阅 latex_elements 的 'maketitle' 关键字的讨论（仅适用于 'manual' 文档类）

修复的错误

• #5725: mathjax: 默认使用 CDN URL 的 “最新” 版本

• #5460:html搜索在某些第三方主题中无法使用

• #5520: LaTeX,标题包自Sphinx 1.6以来的不兼容性

• #5614: autodoc: 增量构建在导入内置模块时损坏

• #5627: qthelp: index.html 在 QtHelp 中缺失

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

• #5754: 文档:修正 LaTeX自定义 中的一些错误

• #5810: LaTeX: sphinxVerbatim 自 1.6.6 起需要明确设置 “hllines” (参考: #1238)

• #5636: C++,修复浮点字面量的解析.

• #5496（再次）:C++,修复部分构建中重复项的断言问题.

• #5724: 快速入门:当 $LC_ALL 为空时 sphinx-quickstart 失败

• #1956: 默认的 conf.py 不符合 PEP8 标准

• #5849: LaTeX: 文档类 \maketitle 被重写,无法使用原始含义替换 Sphinx 自定义的含义

• #5834: apidoc:--tocfile 的帮助信息错误

• #5800: 待办事项:如果在TextElement中定义了待办事项则崩溃

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

• htmlhelp: 当标题包含引号时会生成损坏的.hhk文件

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

不兼容的更改

• #5497: 除非真正需要,否则不要包含 MathJax.js 和 jsmath.js

添加的功能

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

修复的错误

• #5490: latex: 列举列表导致与recommonmark崩溃

• #5492: sphinx-build 在 Python < 3.5.2 时无法构建文档

• #3704: latex: 对于带有图例的图形, \label 定位错误

• #5496: C++,修复当一个符号被声明超过两次时的断言.

• #5493: gettext: 与损坏的模板崩溃

• #5495: 在包含的文件中带文件选项的 csv-table 指令损坏（参考:#4821）

• #5498: autodoc: 无法找到 functools.partial 的类型提示

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

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

• #5548: 修复在已有文件情况下的 ensuredir()

• #5549: graphviz 正确处理不存在的静态目录

• #3002: i18n: 多个脚注引用同一脚注导致重复的节点ID

• #5563: latex: 扩展生成的脚注引用导致LaTeX构建器崩溃

• #5561: 使用旧版本 xindy 时 make all-pdf 失败

• #5557: 快速开始: –no-batchfile 未被遵守

• #3080: texinfo: 多行注释被损坏

• #3080: texinfo: 多行引用已损坏

Release 1.8.1 (发布于 2018年9月22日)

不兼容的更改

• LaTeX \pagestyle 命令已迁移到 LaTeX 模板中. PDF 中没有变化,除非 \sphinxtableofcontents 被自定义了,在 conf.py 中. (参考: #5455)

修复的错误

• #5418: sphinx-build 的默认路径错误 -d/doctrees 文件

• #5421: autodoc 对 autodoc_default_flags 发出弃用警告

• #5422: lambda对象在存储环境时导致PicklingError

• #5417:Sphinx 在 Python 2.7.5 中因语法错误构建失败

• #4911:为非make模式的make.bat添加latexpdf

• #5436: Autodoc 对包含属性/方法的枚举子类无效

• #5437: autodoc: 在导入 eggs 的模块时崩溃

• #5433: latex: ImportError: 无法导入名称 ‘DEFAULT_SETTINGS’

• #5431: autodoc:autofunction 对可调用对象发出警告

• #5457: 修复禁止覆盖时错误消息中的TypeError

• #5453:’howto’ 文档的 PDF 构建没有页码

• #5463: mathbase: 在1.8.0中,math_role和MathDirective消失了

• #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:latexmk 是在 Windows 上执行 make latexpdf 的必要条件

不兼容的更改

1.8.0b2

• #5282: html 主题: 优先参考 HTML 主题的 pygments_style 设置

• 下载文件的URL已更改

• #5127: 快速入门:如果存在,不会覆盖 Makefile 和 make.bat

1.8.0b1

• #5156: sphinx.ext.graphviz 扩展在构建文档的目录中运行 dot ,而不是在文档的根目录中运行.

• #4460: 存储任何数据到环境的扩展应该返回其环境数据结构的版本作为元数据.详细信息请参见 扩展元数据 .

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

• epub_author 和 epub_publisher 的默认值从 'unknown' 更改为 author 的值.这与 conf.py 文件 sphinx-build 生成的内容相同.

• The gettext_compact attribute is removed from document.settings object. Please use config.gettext_compact instead.

• 读取阶段的处理顺序已更改.smart_quotes、sphinx 域、doctree-read 事件和版本化文档树的调用比之前更早.有关更多详细信息,请阅读 Sphinx.add_transform() 的描述

• #4827: 所有 substitution_definition 节点在读取阶段从文档树中移除

• docutils.conf in $HOME or /etc directories are ignored. Only docutils.conf from confdir is obeyed.

• #789::samp: 角色支持用反斜杠转义大括号

• #4811: html_static_path 下的文件被排除在源文件之外.

• latex: 使用 \sphinxcite 进行引用参考,而不是使用 \hyperref

• 配置值 viewcode_import 被重命名为 viewcode_follow_imported_members (参考: #4035)

• #1857: latex: latex_show_pagerefs 不会为引用添加页码引用

• #4648:latex:现在”rubric”元素被渲染为不编号的章节标题

• #4983: html: 生产列表标记的锚点已更改

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

• #5072: 仅保存新文档时也保存环境对象

• #5035: qthelp 构建器允许在 qthelp_namespace 中使用连字符

• LaTeX:使用 lualatex 或 xelatex 时,默认情况下使用 xindy 作为 makeindex 的 UTF-8 可替代品（参考:#5134）.在升级 Sphinx 后,请在新构建之前清理现有项目的 latex 构建目录.

• #5163: html: hlist 项目现在顶部对齐

• highlightlang directive is processed on resolving phase

• #4000: LaTeX: 模板已更改.以下元素已移动到模板中:

  • \begin{document}

  • shorthandoff variable

  • maketitle variable

  • tableofcontents variable

过时的

1.8.0b2

• sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated

• sphinx.io.SphinxI18nReader.line is deprecated

• sphinx.util.i18n.find_catalog_source_file() has changed; the gettext_compact argument has been deprecated

• #5403:sphinx.util.images.guess_mimetype() 已更改; content 参数已弃用

1.8.0b1

• source_parsers 已被弃用

• autodoc_default_flags 已弃用

• quickstart:--epub 选项变为默认设置,因此它已被弃用

• 删除基于函数的指令支持.目前,Sphinx 仅支持基于类的指令（参见 Directive ）

• sphinx.util.docutils.directive_helper() is deprecated

• sphinx.cmdline is deprecated

• sphinx.make_mode is deprecated

• sphinx.locale.l_() is deprecated

• #2157: HTML主题的辅助函数 warn() 已被弃用

• app.override_domain() is deprecated

• app.add_stylesheet() is deprecated

• app.add_javascript() is deprecated

• app.import_object() is deprecated

• app.add_source_parser() has changed; the suffix argument has been deprecated

• sphinx.versioning.prepare() is deprecated

• Config.__init__() has changed; the dirname, filename and tags argument has been deprecated

• Config.check_types() is deprecated

• Config.check_unicode() is deprecated

• sphinx.application.CONFIG_FILENAME is deprecated

• highlightlang directive is deprecated

• BuildEnvironment.load() is deprecated

• BuildEnvironment.loads() is deprecated

• BuildEnvironment.frompickle() is deprecated

• env.read_doc() is deprecated

• env.update() is deprecated

• env._read_serial() is deprecated

• env._read_parallel() is deprecated

• env.write_doctree() is deprecated

• env._nitpick_ignore is deprecated

• env.versionchanges is deprecated

• env.dump() is deprecated

• env.dumps() is deprecated

• env.topickle() is deprecated

• env.note_versionchange() is deprecated

• sphinx.writers.latex.Table.caption_footnotetexts is deprecated

• sphinx.writers.latex.Table.header_footnotetexts is deprecated

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

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

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

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

• sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is deprecated

• sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is deprecated

• sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is deprecated

• sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is deprecated

• sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is deprecated

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

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

• sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated

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

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

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

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

• 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 extension is deprecated

• sphinx.ext.mathbase.math node is deprecated

• sphinx.ext.mathbase.displaymath node is deprecated

• sphinx.ext.mathbase.eqref node is deprecated

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

• sphinx.ext.mathbase.MathDomain is deprecated

• sphinx.ext.mathbase.MathDirective is deprecated

• sphinx.ext.mathbase.math_role is deprecated

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

• sphinx.directives.other.VersionChanges is deprecated

• sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated

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

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

• The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge is deprecated

有关更多详细信息,请参见 弃用的 API 列表 .

添加的功能

1.8.0b2

• #5388: 确保冻结对象描述是可重复的

• #5362:apidoc:添加 --tocfile 选项以更改 ToC 文件名

1.8.0b1

• 添加 config-inited 事件

• 添加 sphinx.config.Any 来表示配置值可以接受任何类型的值

• source_suffix 允许文件扩展名与文件类型的映射

• 添加 author 作为配置值

• #2852: imgconverter: 支持将GIF转换为PNG

• sphinx-build command supports i18n console output

• 增加 app.add_message_catalog() 和 sphinx.locale.get_translations() 以支持第3方扩展的翻译

• 添加了HTML主题的辅助函数 warning()

• 添加 Domain.enumerable_nodes 以管理域的自有可枚举节点（实验性）

• 在 Application APIs 中添加一个新的关键字参数 override

• 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: 分离:rst:role:guilabel 和:rst:role:menuselection 的自定义能力 (参考: #4830)

• 添加 Config.read() 类方法,从配置文件创建一个新的配置对象

• #4866: 在 <div> 标签中包装 graphviz 图表

• 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: 如果设置了 html_baseurl ,则输出 canonical_url 元数据（参考:#4193）

• #5029: autosummary: 将 inherited_members 暴露给模板

• #3784: mathjax: 添加 mathjax_options 以为 mathjax 的脚本标签提供选项

• #726, #969: mathjax: 添加 mathjax_config 以提供 mathjax 的内联配置

• #4362: latex: 如果文档未更改,则不要覆盖 .tex 文件

• #1431: latex: 增加字母数字枚举列表支持

• 添加 latex_use_xindy 以支持 UTF-8 索引,默认值为 True 如果 latex_engine 为 'xelatex' 或 'lualatex' . (参考: #5134, #5192, #5212)

• #4976:SphinxLoggerAdapter.info() 现在支持 location 参数

• #5122: setuptools: 支持 nitpicky 选项

• #2820: autoclass 指令支持嵌套类

• 添加 app.add_html_math_renderer() 用于注册 HTML 的数学渲染器

• 将 trim_doctest_flags 应用于所有构建器 (参见 text, manpages)

• #5140: linkcheck: 为HTTP客户端添加更好的Accept头

• #4614: sphinx-build: 添加 --keep-going 选项以显示所有警告

• 将 math:numref 角色添加到引用方程式（与 eq 相同）

• quickstart: epub 构建器默认启用

• #5246: 增加 singlehtml_sidebars 以配置 singlehtml 构建器的侧边栏

• #5273: doctest: 有条件地跳过doctest

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

• #4075, #5215: autodoc: 添加 autodoc_default_options ,它接受字典形式的选项值

修复的错误

1.8.0b2

• html:如果滚动,搜索框会覆盖其他元素

• i18n: 翻译目录的警告行号错误 (refs: #5321)

• #5325: latex: 交叉引用因多重标记对象而损坏

• C++,修复符号添加和查找的问题.查找在部分构建中不再中断.另见 #5337.

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

• #5282: html 主题: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: 当 “self” 列在 toctree 中时,书脊已被破坏（参考:#4611）

• #344:autosummary 无法理解模块级属性的文档字符串

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

• #5126: C++,为某些模板参数类型添加缺失的 isPack 方法.

• #5187: C++,在声明符上解析属性.

• C++,解析删除表达式和基本的新表达式.

• #5002: graphviz: SVG 不适应列宽

移除的功能

1.8.0b1

• sphinx.ext.pngmath extension

文档

1.8.0b1

• #5083: 修复国际化的错误 make.bat 选项.

• #5115: napoleon: 将#4613中添加的警告信息添加到文档中.

Previous

Sphinx 2.0

Next

Sphinx 1.7