Sphinx 2.0

发布 2.0.1 (发布于 2019 年 4 月 8 日)

修复的 Bug

  • LaTeX: 某些系统标签未翻译

  • RemovedInSphinx30Warning 标记为待处理

  • 未发出弃用警告

    • sphinx.application.CONFIG_FILENAME

    • sphinx.builders.htmlhelp

    • viewcode_import

  • #6208: C++，正确解析前缀为短 xref 的完整 xref

  • #6220, #6225: napoleon: 对于有引用的 raised section 抛出 AttributeError

  • #6245: 导入 SerializingHTMLBuilder 时出现循环导入错误

  • #6243: LaTeX: 忽略 latex_elements 的“releasename”设置

  • #6244: html: 搜索功能在第三方主题中损坏

  • #6263: html: HTML5Translator 因无效的字段节点崩溃

  • #6262: html 主题: bizstyle 主题中字段列表的样式已更改

发布 2.0.0 (发布于 2019 年 3 月 29 日)

依赖项

2.0.0b1

  • LaTeX 构建器现在依赖于 TeX Live 2015 或更高版本。

  • LaTeX 构建器（使用 'pdflatex' latex_engine）将通过文本字体处理文本（非数学标记）中的 Unicode 希腊字母，而不会将它们转义为数学标记。请参阅 latex_elements 的 'fontenc' 键的讨论；这种（可选的）希腊语支持会增加，例如在 Ubuntu xenial 上，texlive-lang-greek 和（如果未修改默认字体设置）cm-super(-minimal) 作为额外的 Sphinx LaTeX 要求。

  • LaTeX 构建器，如果 latex_engine 设置为 'xelatex' 或 'lualatex'，则（默认情况下）需要 FreeFont 字体，在 Ubuntu xenial 中，这些字体由软件包 fonts-freefont-otf 提供，例如在 Fedora 29 中通过软件包 texlive-gnu-freefont 提供。

  • requests 2.5.0 或更高版本

  • six 包不再是依赖项

  • sphinxcontrib-websupport 包不再是依赖项

  • 部分包已拆分为子包

    • sphinxcontrib.applehelp

    • sphinxcontrib.devhelp

    • sphinxcontrib.htmlhelp

    • sphinxcontrib.jsmath

    • sphinxcontrib.serializinghtml

    • sphinxcontrib.qthelp

不兼容的变更

2.0.0b1

  • 放弃对 python 2.7 和 3.4 的支持

  • 放弃对 Docutils 0.11 的支持

  • 放弃在 1.7.x 中弃用的功能和 API

  • master_doc 的默认设置已更改为 'index'，该设置长期以来一直作为 sphinx-quickstart 的默认设置。

  • LaTeX: 将消息资源移动到 sphinxmessage.sty

  • LaTeX: 停止对某些标签使用 \captions<lang> 宏

  • LaTeX: 对于 'xelatex' 和 'lualatex'，使用 FreeFont OpenType 字体作为默认选择（refs: #5645）

  • LaTeX: 'xelatex' 和 'lualatex' 现在在代码块中使用 \small（由于 FreeMono 字符宽度），就像 'pdflatex' 已经那样做（由于 Courier 字符宽度）。如果使用其他 OpenType 字体，您可能需要通过 latex_elements 'fvset' 键进行调整（refs: #5768）

  • LaTeX: 文本中的希腊字母不会被转义为数学模式标记，它们将使用文本字体而不是数学字体。为了使其生效（当然，只有在文档需要时），必须将 LGR 字体编码添加到 latex_elements 的 'fontenc' 键中。

  • LaTeX: 将 language 设置为 'en' 会触发 fncychap 的 Sonny 选项，现在是 Bjarne 以匹配未指定语言的情况。（refs: #5772）

  • #5770: doctest: 在高亮 doctest 块时遵循 highlight_language。因此，它们默认被高亮为 python3。

  • HTMLTranslator、HTML5Translator 和 ManualPageTranslator 的参数顺序已更改

  • LaTeX: 以前在加载 'manual' 文档类时完成的 \l@section 和 \l@subsection 的硬编码重定义现在在 \sphinxtableofcontents 时执行。这意味着自定义用户定义（来自 LaTeX 序言）现在将被覆盖。请使用 \sphinxtableofcontentshook 插入自定义用户定义。请参阅 宏。

  • quickstart: 简化生成的 conf.py

  • #4148: quickstart: 某些问题已删除。它们仍然可以通过命令行选项指定

  • websupport: 从 Sphinx 核心中解绑。请使用 sphinxcontrib-websupport

  • C++：基类的可见性现在始终按输入中的显示方式呈现。也就是说，private 现在会显示，而以前会被省略。

  • LaTeX: 包含超大图像时，即使使用了宽度和/或高度选项，也会按比例缩放以不超过文本宽度和高度。（refs: #5956）

  • epub: epub_title 默认为 project 选项

  • #4550: 所有没有 align 选项的表格和图表都居中显示

  • #4587: html: 默认输出 HTML5

2.0.0b2

  • texinfo: 图像文件被复制到 name-figure 目录

已弃用

2.0.0b1

  • 对评估 Python 2 语法的支持已弃用。这包括应转换为 Python 3 的配置文件。

  • EpubBuilder.build_mimetype()、EpubBuilder.build_container()、EpubBuilder.bulid_content()、EpubBuilder.build_toc() 和 EpubBuilder.build_epub() 的参数

  • Epub3Builder.build_navigation_doc() 的参数

  • 配置变量

    • html_experimental_html5_writer

  • autodoc.Documenter.get_doc(), autodoc.DocstringSignatureMixin.get_doc(), autodoc.DocstringSignatureMixin._find_signature() 和 autodoc.ClassDocumenter.get_doc() 的 encoding 参数已弃用。

  • sphinx.ext.autodoc.importer._MockModule 的 importer 参数

  • sphinx.search.WordCollector. is_meta_keywords() 的 nodetype 参数

  • env.doc2path() 的 suffix 参数已弃用。

  • env.doc2path() 的字符串样式 base 参数已弃用。

  • 允许省略重写的 IndexBuilder.feed() 方法中的 filename 参数的回退已弃用。

  • sphinx.addnodes.abbreviation

  • sphinx.application.Sphinx._setting_up_extension

  • sphinx.builders.epub3.Epub3Builder.validate_config_value()

  • sphinx.builders.html.SingleFileHTMLBuilder

  • sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()

  • sphinx.cmd.quickstart.term_decode()

  • sphinx.cmd.quickstart.TERM_ENCODING

  • sphinx.config.check_unicode()

  • sphinx.config.string_classes

  • sphinx.domains.cpp.DefinitionError.description

  • sphinx.domains.cpp.NoOldIdError.description

  • sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded

  • sphinx.ext.autodoc.importer._MockImporter

  • sphinx.ext.autosummary.Autosummary.warn()

  • sphinx.ext.autosummary.Autosummary.genopt

  • sphinx.ext.autosummary.Autosummary.warnings

  • sphinx.ext.autosummary.Autosummary.result

  • sphinx.ext.doctest.doctest_encode()

  • sphinx.io.SphinxBaseFileInput

  • sphinx.io.SphinxFileInput.supported

  • sphinx.io.SphinxRSTFileInput

  • sphinx.registry.SphinxComponentRegistry.add_source_input()

  • sphinx.roles.abbr_role()

  • sphinx.roles.emph_literal_role()

  • sphinx.roles.menusel_role()

  • sphinx.roles.index_role()

  • sphinx.roles.indexmarkup_role()

  • sphinx.testing.util.remove_unicode_literal()

  • sphinx.util.attrdict

  • sphinx.util.force_decode()

  • sphinx.util.get_matching_docs()

  • sphinx.util.inspect.Parameter

  • sphinx.util.jsonimpl

  • sphinx.util.osutil.EEXIST

  • sphinx.util.osutil.EINVAL

  • sphinx.util.osutil.ENOENT

  • sphinx.util.osutil.EPIPE

  • sphinx.util.osutil.walk()

  • sphinx.util.PeekableIterator

  • sphinx.util.pycompat.NoneType

  • sphinx.util.pycompat.TextIOWrapper

  • sphinx.util.pycompat.UnicodeMixin

  • sphinx.util.pycompat.htmlescape

  • sphinx.util.pycompat.indent

  • sphinx.util.pycompat.sys_encoding

  • sphinx.util.pycompat.terminal_safe()

  • sphinx.util.pycompat.u

  • sphinx.writers.latex.ExtBabel

  • sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()

  • sphinx.writers.latex.LaTeXTranslator.babel_defmacro()

  • sphinx.writers.latex.LaTeXTranslator.collect_footnotes()

  • sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()

  • sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()

  • sphinx.writers.text.TextTranslator._make_depart_admonition()

  • LaTeX 模板的模板变量

    • logo

    • 数字图_格式

    • pageautorefname

    • translatablestrings

有关更多详细信息，请参阅 已弃用 API 列表。

新增功能

2.0.0b1

  • #1618: 生成的 HTML 文档的搜索结果预览更加用户友好：Sphinx 现在将片段呈现为相应的 HTML，而不是显示为原始 reStructuredText 标记。这意味着 Sphinx 扩展 Sphinx: pretty search results 不再需要。请注意，您自定义或第三方 HTML 模板的搜索功能更改可能会覆盖此改进。

  • #4182: autodoc: 支持 suppress_warnings

  • #5533: autodoc: autodoc_default_options 支持 member-order

  • #5394: autodoc: 在模拟对象中显示可读的类型注释名称

  • #5459: autodoc: autodoc_default_options 接受 True 作为值

  • #1148: autodoc: 为装饰器添加 autodecorator 指令

  • #5635: autosummary: 添加 autosummary_mock_imports 以在导入目标时模拟外部库

  • #4018: htmlhelp: 添加 htmlhelp_file_suffix 和 htmlhelp_link_suffix

  • #5559: text: 支持复杂表格（colspan 和 rowspan）

  • LaTeX: 支持在非西里尔文档中渲染（尚未在数学中）希腊语和西里尔语 Unicode 字母，即使 latex_engine 设置为 'pdflatex' (refs: #5645)

  • #5660: versionadded、versionchanged 和 deprecated 指令现在除了通用 versionmodified 类之外，还生成具有其特定 CSS 类（分别为 added、changed 和 deprecated）。

  • #5841: apidoc: 为 sphinx-apidoc 添加 –extensions 选项

  • #4981: C++，添加了一个别名指令，用于插入声明列表，该列表引用现有声明（例如，用于制作概要）。

  • C++：添加 cpp:struct 作为 cpp:class 的补充。

  • #1341: HTML 搜索将包含三个或更多字符的搜索词的单词视为匹配。

  • #4611: epub: 显示重复目录条目的警告

  • #1851: 允许省略 code-block 指令的参数。如果省略，它将遵循 highlight 或 highlight_language

  • #4587: html: 添加 html4_writer 以使用旧的 HTML4 写入器

  • #6016: HTML 搜索: 搜索摘要的占位符可防止搜索结果链接在搜索终止时改变其位置。这使得导航搜索结果更加容易。

  • #5196: linkcheck 也检查远程图像是否存在

  • #5924: githubpages: 当 html_baseurl 设置时，为自定义域创建 CNAME 文件

  • #4261: autosectionlabel: 通过新的配置值限制带标签的章节；autosectionlabel_maxdepth

修复的 Bug

2.0.0b1

  • #1682: LaTeX: 写入器不应翻译希腊语 Unicode，而应使用 textgreek 包

  • #5247: LaTeX: 在俄罗斯语言和 'xelatex' 或 'lualatex' 作为 latex_engine 的默认字体配置下，PDF 无法构建 (refs: #5251)

  • #5248: LaTeX: 节标题中的希腊 Unicode 字母从 PDF 书签中消失

  • #5249: LaTeX: 数学指令中的 Unicode 希腊字母导致 PDF 构建中断（修复需要额外设置，请参阅 latex_elements 'textgreek' 键和/或 latex_engine 设置）

  • #5772: LaTeX: 如果将 Bjarne 风格的 fncychap 作为语言选项传递，它是否也应该用于英语？

  • #5179: LaTeX: (仅限 lualatex) 通过 \textgreater{} 转义 > 是不够的，因为 \textgreater{}\textgreater{} 会应用 TeX 连字

  • LaTeX: 如果省略 latex_documents，项目名称不被转义

  • LaTeX: 如果省略 latex_documents，不显示作者

  • HTML: 对于一个词汇表有多个描述的术语，会生成无效的 HTML5 文件（refs: #4611）

  • QtHelp: .qhp 文件中使用与操作系统相关的路径分隔符

  • HTML 搜索: 当使用多个搜索词且其中一个词少于三个字符时，搜索总是返回空结果

2.0.0b2

  • #6096: html: 锚点链接未添加到图中

  • #3620: html: 延迟加载 searchindex.js，而不是通过 ajax 加载

  • #6113: html: 表格单元格和列表项有大边距

  • #5508: highlight 指令的 linenothreshold 选项被忽略

  • texinfo: make install-info 导致语法错误

  • texinfo: make install-info 在 macOS 上失败

  • #3079: texinfo: 在 make install-info 时，图像文件未被复制

  • #5391: 标题中的交叉引用呈现为文字

  • #5946: C++，修复 LaTeX (和 singlehtml) 中的 cpp:alias 问题

  • #6147: citation_reference 节点的 classes 属性丢失

  • 当带有 classes 属性的自定义 citation_reference 节点引用缺失引用时，会引发 AssertionError（refs: #6147）

  • #2155: 支持 code 指令

  • C++，修复带括号初始化器的解析。

  • #6172: 对旧式索引节点抛出 AttributeError

  • #4872: inheritance_diagram: 正确描述 docs 中 parts 选项的行为，允许负值。

  • #6178: i18n: 隐藏 TOC 的翻译中缺少标题

2.0.0 最终版

  • #6196: py 领域: 生成了意外前缀

测试

2.0.0b1

  • 停止使用 SPHINX_TEST_TEMPDIR 环境变量

2.0.0b2

  • 添加了一个辅助函数: sphinx.testing.restructuredtext.parse()