Sphinx 2.0

版本2.0.1（发布于2019年4月8日）

Bug 修复

  • LaTeX：一些系统标识未翻译

  • 移除 Sphinx3.0 中被标为待定的警告

  • 禁用弃用警告

    • sphinx.application.CONFIG_FILENAME

    • sphinx.builders.htmlhelp

    • viewcode_import

  • ＃6208：C ++，正确解析具有短外部参照作为前缀的完整外部参照

  • ＃6220，＃6225：napoleon：对于具有引用的凸起部分，引发AttributeError

  • ＃6245：导入 SerializingHTMLBuilder 时出现循环导入错误

  • #6243：LaTeX：latex_elements 的 'releasename' 设置失效

  • ＃6244：html：搜索功能被第三方主题破坏

  • ＃6263：html：无效的字段节点导致 HTML5 Translator 崩溃

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

2.0.0版（2019年3月29日发行）

依赖

2.0.0b1

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

  • LaTeX 生成器（带有 'pdflatex' latex_engine）将通过文本字体处理文本中的 Unicode 希腊字母（而不是数学标记），并且不会将它们转义为数学标记参见 latex_elements 的 'fontenc' 键的讨论； 此类（可选）对希腊语的支持在其他示例中添加了例如 Ubuntu Ubuntu上的 texlive-lang-greek 和（如果未修改默认字体设置） cm-super（-minimal） Sphinx LaTeX 要求。

  • LaTeX 生成器的 latex_engine 设置为 xelatex 或 lualatex 所需（默认情况下）需要 FreeFont 字体，在 Ubuntu xenial 中由 package 提供 fonts-freefont-otf 和例如 在 Fedora 29中通过软件包 texlive-gnu-freefont。

  • 要求 2.5.0 或更高版本

  • 这六个 package 不再存在依赖

  • sphinxcontrib-websupport 包现不存在依赖

  • 一些程序包被分为子程序包：

    • sphinxcontrib.applehelp

    • sphinxcontrib.devhelp

    • sphinxcontrib.htmlhelp

    • sphinxcontrib.jsmath

    • sphinxcontrib.serializinghtml

    • sphinxcontrib.qthelp

不兼容的变更

2.0.0b1

  • 弃用对 Python 2.7 和 3.4 的支持

  • Drop Docutils 0.11 support

  • 弃用 1.7.x 中的删除功能和 API

  • The default setting for master_doc is changed to 'index' which has been longly used as default of 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”字体编码必须添加到 latex_elements 的 fontenc 键中，这样才能正常工作（当然，只有在文档需要它的情况下）。

  • LaTeX： language 设置为 en 触发了 fncychap 的 Sonny 选项，现在是 Bjarne 来匹配未指定语言的大小写。（参考：#5772）

  • #5770：doctest: Follow highlight_language on highlighting doctest块。因此，它们在默认情况下高亮显示为 Python3。

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

  • LaTeX：hard-coded 的重新定义 \l@section 以及 \l@subsection 以前是在加载 'manual' 时完成的，docclass 稍后在 \sphinxtableofcontents 时执行。这意味着来自LaTeX preamble 的自定义用户定义现在被覆盖。使用 \sphinxtableofcontentshook 插入自定义用户定义。请参见 宏。

  • quickstart：简化生成的 conf.py

  • #4148：快速入门：删除了一些问题。已删除问题仍然可以通过命令行选项指定。

  • websupport: unbundled from Sphinx core. Please use sphinxcontrib-websupport

  • C++中，基类的可见性现在总是呈现为输入中的当前。也就是说，“private” 现在显示出来了，它以前是省略的。

  • LaTeX：包含超大图像的图形重新缩放到不超过文本的宽度和高度，即使使用了宽度和/或高度选项。（参考: #5956）

  • epub： project 默认值是 epub_title 。

  • #4550：所有没有“align”选项的表格和图形都显示在中间

  • #4587：html：默认输出 HTML5

2.0.0b2

  • texinfo：图像文件被复制到 “name figure” 目录中

已弃用

2.0.0b1

  • 不推荐使用对 Python2 语法求值的支持。这包括应该转换为 Python3 的配置文件。

  • EpubBuilder.build_mimetype(), EpubBuilder.build_container(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and 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”参数。

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

  • “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

    • numfig_format

    • pageautorefname

    • translatablestrings

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

新增特性

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：text：支持复杂表格操作（合并行、 拆分行 ）

  • LaTeX：支持在非西里尔文文档中呈现希腊语和西里尔文 Unicode 母（还没有在数学中），即使使用“'pdflatex'” latex_engine （参考：#5645）

  • #5660：“versionadded”、“versionchanged” 和 “deprecated” 指令现在除了泛型的“versionmodified” 类之外，还生成了自己的特定 CSS 类（分别是“added”、“changed”和“deprecated”）。

  • #5841：apidoc：给 sphinx-apidoc 增加 --extensions 选项。

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

  • C++：添加 cpp:struc 用于补充 cpp:class。

  • #1341: the HTML search considers words that contain a search term of length three or longer a match.

  • #4611：epub：复制 ToC 条目时显示警告

  • #1851：允许省略以下参数 code-block 指令。如果省略，则允许使用 highlight 或 highlight_language

  • #4587: html: Add html4_writer to use old HTML4 writer

  • #6016：HTML 搜索：搜索摘要的占位符禁止在搜索终止时更改搜索结果链接位置。这使得导航搜索结果更容易。

  • #5196：linkcheck 也检查远程映像是否存在。

  • #5924：githubpages：当设定了“ html_baseurl ”时，为定制域创建 CNAME 文件。

  • #4261：autosectionlabel：按新配置值限制已标记的节 autosectionlabel_maxdepth

Bug 修复

2.0.0b1

  • #1682：LaTeX：作者在使用 textgreek 包时，不应翻译 Greek unicode。

  • #5247：LaTeX：PDF 没有使用俄语和“Xeletex”或“lualatex”的默认字体配置生成，例如 latex_engine （参考：#5251）

  • #5248：LaTeX：PDF 书签中部分标题中的希腊字母消失

  • #5249：LaTeX：Unicode 希腊字母在数学指令中破坏了 PDF build（修复需要额外的设置，请参阅 latex_elements 'textgreek' 键和/或 latex_engine 设置）

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

  • #5179：LaTeX：（仅限 lualatex）由 “textgreater{}”转义“>`” 是不够的，因为 “textgreater{}textgreater{}” 应用了 TeX 连字

  • 如果 latex_documents 省略，则不转义project名字

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

  • HTML：对于一个描述包含多个术语的词汇表，生成无效的 HTML5 文件（参考：#4611）

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

  • HTML 搜索：当使用多个搜索词且一个词少于三个字符时，搜索始终不返回任何内容

2.0.0b2

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

  • #3620：html：延迟 searchindex.js 而非通过 ajax 来加载它

  • #6113：html：表格单元格和列表项的边距很大

  • #5508: “highlight” 指令的 “linenothreshold” 选项被忽视

  • texinfo：make install-info 引发错误

  • texinfo：在 macOS 上 “make install-info”报错

  • #3079：texinfo：“make install-info” 中图片文件未被复制

  • #5391：标题中的交叉引用呈现为文本

  • #5946：C++, 修复 LaTeX （以及单个HTML文件）中 “cpp:alias” 问题

  • #6147：“citation_reference” 节点的类属性丢失

  • 当具有 classes 属性的自定义 “citation_reference” 节点引用缺少引用时引发AssertionError（参考：#6147）

  • #2155：支持 code 指令

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

  • #6172：旧样式的索引节点引发 AttributeError

  • #4872：inheritance_diagram：正确描述文档中“parts”选项的行为，允许负值。

  • #6178：18n：隐藏目录的翻译中缺少标题

2.0.0 终版

  • #6196：Py domain：生成了意外的前缀

测试

2.0.0b1

  • 停用 “SPHINX_TEST_TEMPDI”

2.0.0b2

  • 新增帮助功能 sphinx.testing.restructuredtext.parse()