Sphinx 2.0

版本 2.0.1（发行于 2019 年 4 月 08 日）

修复的错误

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

  • RemovedInSphinx30Warning 被标记为待定

  • 不发出弃用警告

    • sphinx.application.CONFIG_FILENAME

    • sphinx.builders.htmlhelp

    • viewcode_import

  • #6208: C++,正确解析恰好以短引用为前缀的完整交叉引用

  • #6220, #6225: napoleon: 引发的节有引用时引发AttributeError

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

  • #6243: LaTeX: ‘releasename’ 设置在 latex_elements 中被忽略

  • #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构建器当:confval:latex_engine 设置为 'xelatex' 或 'lualatex' 时（默认情况下）需要 FreeFont 字体,在Ubuntu xenial中,这些字体由 fonts-freefont-otf 包提供,而在Fedora 29中通过 texlive-gnu-freefont 包提供.

  • requests 2.5.0 或更高版本

  • 六个包不再是依赖项

  • 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 字体作为默认选择（参考:#5645）

  • LaTeX:'xelatex' 和 'lualatex' 现在在代码块中使用 \small （由于 FreeMono 字符宽度的原因）,就像 'pdflatex' 已经做的那样（由于 Courier 字符宽度）.您可能需要通过 latex_elements 的 'fvset' 键进行调整,以便使用某些其他的 OpenType 字体（参考:#5768）.

  • LaTeX:文本中的希腊字母不会被转义为数学模式标记,它们将使用文本字体而不是数学字体.必须将 LGR 字体编码添加到:confval:latex_elements 的 'fontenc' 键中,以使其正常工作（当然,这仅在文档需要时）.

  • LaTeX: 将 language 设置为 'en' 触发了 fncychap 的 Sonny 选项,现在它变为 Bjarne 以匹配未指定语言的情况. (参考: #5772)

  • #5770: doctest: 根据 highlight_language 规则高亮 doctest 块.因此,它们默认以 python3 的格式高亮显示.

  • The order of argument for HTMLTranslator, HTML5Translator and ManualPageTranslator are changed

  • LaTeX:在加载 'manual' 文档类时进行的 \l@section 和 \l@subsection 的硬编码重定义现在在 \sphinxtableofcontents 时执行.这意味着 LaTeX 前言中的自定义用户定义现在会被覆盖.使用 \sphinxtableofcontentshook 来插入自定义用户定义.请参见 宏 .

  • quickstart: 简化生成的 conf.py

  • #4148: 快速入门: 一些问题已被移除.用户仍然可以通过命令行选项进行指定

  • websupport:已从 Sphinx 核心中分离.请使用 sphinxcontrib-websupport

  • C++中,基类的可见性现在始终在输入中呈现为存在.也就是说,现在显示 private ,而之前是省略的.

  • LaTeX:大图像的图形包含会被重新缩放,以不超过文本的宽度和高度,即使使用了宽度和/或高度选项.(参考:#5956)

  • epub:epub_title 默认为 project 选项

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

  • #4587: html: 默认输出 HTML5

2.0.0b2

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

Deprecated

2.0.0b1

  • 支持评估 Python 2 语法的功能已被弃用.这包括应该转换为 Python 3 的配置文件.

  • The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_container(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and EpubBuilder.build_epub()

  • The arguments of Epub3Builder.build_navigation_doc()

  • 配置变量

    • html_experimental_html5_writer

  • The encoding argument of autodoc.Documenter.get_doc(), autodoc.DocstringSignatureMixin.get_doc(), autodoc.DocstringSignatureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc() are deprecated.

  • The importer argument of sphinx.ext.autodoc.importer._MockModule

  • The nodetype argument of sphinx.search.WordCollector. is_meta_keywords()

  • The suffix argument of env.doc2path() is deprecated.

  • The string style base argument of env.doc2path() is deprecated.

  • 允许在重写的 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

    • numfig_format

    • pageautorefname

    • translatablestrings

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

功能新增

2.0.0b1

  • #1618: 生成的HTML文档的搜索结果预览更加适合读者使用:现在Sphinx不再以原始的reStructuredText标记显示片段,而是渲染相应的HTML.这意味着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: 文本: 支持复杂表格 (colspan 和 rowspan)

  • LaTeX: 支持在非西里尔文档中渲染希腊字母和西里尔字母的Unicode字符（尚不支持数学模式）,即使在 latex_engine 为 'pdflatex' 的情况下也可使用（参考:#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: 对于重复的 ToC 条目显示警告

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

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

  • #6016: HTML搜索:搜索摘要的占位符防止搜索结果链接在搜索终止时改变位置.这使得导航搜索结果变得更简单.

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

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

  • #4261: autosectionlabel: 通过新的配置值限制标记的章节; autosectionlabel_maxdepth

修复的错误

2.0.0b1

  • #1682: LaTeX: 写入器不应翻译希腊字母的unicode,而应使用textgreek包

  • #5247: LaTeX: 使用默认字体配置、俄语和 'xelatex' 或 'lualatex' 作为 latex_engine 时 PDF 无法构建 (参考: #5251)

  • #5248: LaTeX: 希腊字母在节标题中从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文件（参考:#4611）

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

  • HTML搜索:当使用多个搜索词且其中一个搜索词短于三个字符时,搜索始终返回无结果

2.0.0b2

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

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

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

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

  • 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 属性丢失

  • 当自定义 citation_reference 节点的类属性引用缺失的引用时,会引发 AssertionError（引用:#6147）

  • #2155: 支持 code 指令

  • C++,修复花括号初始化器的解析.

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

  • #4872: inheritance_diagram: 正确描述文档中 parts 选项的行为,允许负值.

  • #6178: i18n: 隐藏的目录中缺失翻译的标题

2.0.0 最终版

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

Testing

2.0.0b1

  • 停止使用 SPHINX_TEST_TEMPDIR 环境变量

2.0.0b2

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