Sphinx更新

Release 3.0.0 (in development)

依赖

不兼容的变化

• Drop features and APIs deprecated in 1.8.x

弃用

添加功能

修正了错误

测试

版本 2.1.0 (开发中)

依赖

不兼容的变化

• 忽略没有直接赋予 Builder.build_specific() API的文件扩展名的文件名

• #6230: The anchor of term in glossary directive is changed if it is consisted by non-ASCII characters

弃用

• sphinx.builders.latex.LaTeXBuilder.apply_transforms()

• sphinx.builders._epub_base.EpubBuilder.esc()

• sphinx.directives.Acks

• sphinx.directives.Author

• sphinx.directives.Centered

• sphinx.directives.Class

• sphinx.directives.CodeBlock

• sphinx.directives.Figure

• sphinx.directives.HList

• sphinx.directives.Highlight

• sphinx.directives.Include

• sphinx.directives.Index

• sphinx.directives.LiteralInclude

• sphinx.directives.Meta

• sphinx.directives.Only

• sphinx.directives.SeeAlso

• sphinx.directives.TabularColumns

• sphinx.directives.TocTree

• sphinx.directives.VersionChange

• sphinx.domains.python.PyClassmember

• sphinx.domains.python.PyModulelevel

• sphinx.domains.std.StandardDomain._resolve_citation_xref()

• sphinx.domains.std.StandardDomain.note_citations()

• sphinx.domains.std.StandardDomain.note_citation_refs()

• sphinx.domains.std.StandardDomain.note_labels()

• sphinx.environment.NoUri

• sphinx.ext.apidoc.format_directive()

• sphinx.ext.apidoc.format_heading()

• sphinx.ext.autodoc.importer.MockFinder

• sphinx.ext.autodoc.importer.MockLoader

• sphinx.ext.autodoc.importer.mock()

• sphinx.ext.autosummary.autolink_role()

• sphinx.ext.imgmath.DOC_BODY

• sphinx.ext.imgmath.DOC_BODY_PREVIEW

• sphinx.ext.imgmath.DOC_HEAD

• sphinx.transforms.CitationReferences

• sphinx.transforms.SmartQuotesSkipper

• sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()

• sphinx.util.node.find_source_node()

• sphinx.util.i18n.find_catalog()

• sphinx.util.i18n.find_catalog_files()

• sphinx.util.i18n.find_catalog_source_files()

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

添加功能

• 添加一个辅助类 sphinx.transforms.post_transforms.SphinxPostTransform

• Add helper methods

  • PythonDomain.note_module()

  • PythonDomain.note_object()

  • SphinxDirective.set_source_info()

• #6180: 支持 --keep-going 使用BuildDoc安装命令

• math 指令现在支持 :class: 选项

• #6310: imgmath: let imgmath_use_preview work also with the SVG format for images rendering inline math

• todo: todo 指令现在支持 :name: 选项

• Enable override via environment of SPHINXOPTS and SPHINXBUILD Makefile variables (refs: #6232, #6303)

• #6287: autodoc: Unable to document bound instance methods exported as module functions

• #6289: autodoc: autodoc_default_options now supports imported-members option

• #4777: autodoc: Support coroutine

• #6212 autosummary: Add autosummary_imported_members to display imported members on autosummary

• #6271: make clean is catastrophically broken if building into ‘.’

• #4777: py domain: Add :async: option to py:function directive

• py domain: Add :async:, :classmethod: and :staticmethod: options to py:method directive

修正了错误

• #6230: Inappropriate node_id has been generated by glossary directive if term is consisted by non-ASCII characters

• #6213: ifconfig: contents after headings are not shown

• commented term in glossary directive is wrongly recognized

• #6299: rst domain: rst:directive directive generates waste space

• Generated Makefiles lack a final EOL (refs: #6232)

测试

Release 2.0.1 (released Apr 08, 2019)

修正了错误

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

• RemovedInSphinx30Warning is marked as pending

• deprecation warnings are not emitted

  • sphinx.application.CONFIG_FILENAME

  • sphinx.builders.htmlhelp

  • viewcode_import

• #6208: C++, properly parse full xrefs that happen to have a short xref as prefix.

• #6220, #6225: napoleon: AttributeError is raised for raised section having references

• #6245: circular import error on importing SerializingHTMLBuilder

• #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored

• #6244: html: Search function is broken with 3rd party themes

• #6263: html: HTML5Translator crashed with invalid field node

• #6262: html theme: The style of field lists has changed in bizstyle theme

版本 2.0.0 (2019年3月29日)

依赖

2.0.0b1

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

• LaTeX构建器(带有 'pdflatex' latex_engine)将通过文本字体处理文本中的Unicode希腊字母(不是数学标记), 并且不会将它们转义为数学标记。请参阅 'fontenc' 键的讨论 latex_elements ; 希腊语的这种(可选)支持添加, 例如在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 。

• 要求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

• The default setting for master_doc is changed to 'index' which has been longly used as default of sphinx-quickstart.

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

• LaTeX: Stop using \captions<lang> macro for some labels

• LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts as default choice (refs: #5645)

• LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to FreeMono character width) like 'pdflatex' already did (due to Courier character width). You may need to adjust this via latex_elements 'fvset' key, in case of usage of some other OpenType fonts (refs: #5768)

• LaTeX: Greek letters in text are not escaped to math mode mark-up, and they will use the text font not the math font. The LGR font encoding must be added to the 'fontenc' key of latex_elements for this to work (only if it is needed by the document, of course).

• LaTeX: setting the language to 'en' triggered Sonny option of fncychap, now it is Bjarne to match case of no language specified. (refs: #5772)

• #5770: doctest: Follow highlight_language on highlighting doctest block. As a result, they are highlighted as python3 by default.

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

• LaTeX: hard-coded redefinitions of \l@section and \l@subsection formerly done during loading of 'manual' docclass get executed later, at time of \sphinxtableofcontents. This means that custom user definitions from LaTeX preamble now get overwritten. Use \sphinxtableofcontentshook to insert custom user definitions. See 宏.

• quickstart: Simplify generated conf.py

• #4148: quickstart: some questions are removed. They are still able to specify via command line options

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

• C++, the visibility of base classes is now always rendered as present in the input. That is, private is now shown, where it was ellided before.

• LaTeX: graphics inclusion of oversized images rescales to not exceed the text width and height, even if width and/or height option were used. (refs: #5956)

• epub: epub_title defaults to the project option

• #4550: All tables and figures without align option are displayed to center

• #4587: html: Output HTML5 by default

2.0.0b2

• texinfo: image files are copied into name-figure directory

弃用

2.0.0b1

• Support for evaluating Python 2 syntax is deprecated. This includes configuration files which should be converted to 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()

• The config variables

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

• The fallback to allow omitting the filename argument from an overridden IndexBuilder.feed() method is deprecated.

• 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()

• template variables for LaTeX template

  • logo

  • numfig_format

  • pageautorefname

  • translatablestrings

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

添加功能

2.0.0b1

• #1618: The search results preview of generated HTML documentation is reader-friendlier: instead of showing the snippets as raw reStructuredText markup, Sphinx now renders the corresponding HTML. This means the Sphinx extension Sphinx: pretty search results is no longer necessary. Note that changes to the search function of your custom or 3rd-party HTML template might overwrite this improvement.

• #4182: autodoc: Support suppress_warnings

• #5533: autodoc: autodoc_default_options supports member-order

• #5394: autodoc: Display readable names in type annotations for mocked objects

• #5459: autodoc: autodoc_default_options accepts True as a value

• #1148: autodoc: Add autodecorator directive for decorators

• #5635: autosummary: Add autosummary_mock_imports to mock external libraries on importing targets

• #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix

• #5559: text: Support complex tables (colspan and rowspan)

• LaTeX: support rendering (not in math, yet) of Greek and Cyrillic Unicode letters in non-Cyrillic document even with 'pdflatex' as latex_engine (refs: #5645)

• #5660: The versionadded, versionchanged and deprecated directives are now generated with their own specific CSS classes (added, changed and deprecated, respectively) in addition to the generic versionmodified class.

• #5841: apidoc: Add –extensions option to sphinx-apidoc

• #4981: C++, added an alias directive for inserting lists of declarations, that references existing declarations (e.g., for making a synopsis).

• C++: add cpp:struct to complement cpp:class.

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

• #4611: epub: Show warning for duplicated ToC entries

• #1851: Allow to omit an argument for code-block directive. If omitted, it follows highlight or highlight_language

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

• #6016: HTML search: A placeholder for the search summary prevents search result links from changing their position when the search terminates. This makes navigating search results easier.

• #5196: linkcheck also checks remote images exist

• #5924: githubpages: create CNAME file for custom domains when html_baseurl set

• #4261: autosectionlabel: restrict the labeled sections by new config value; autosectionlabel_maxdepth

修正了错误

2.0.0b1

• #1682: LaTeX: writer should not translate Greek unicode, but use textgreek package

• #5247: LaTeX: PDF does not build with default font config for Russian language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)

• #5248: LaTeX: Greek letters in section titles disappear from PDF bookmarks

• #5249: LaTeX: Unicode Greek letters in math directive break PDF build (fix requires extra set-up, see latex_elements 'textgreek' key and/or latex_engine setting)

• #5772: LaTeX: should the Bjarne style of fncychap be used for English also if passed as language option?

• #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not enough as \textgreater{}\textgreater{} applies TeX-ligature

• LaTeX: project name is not escaped if latex_documents omitted

• LaTeX: authors are not shown if latex_documents omitted

• HTML: Invalid HTML5 file is generated for a glossary having multiple terms for one description (refs: #4611)

• QtHelp: OS dependent path separator is used in .qhp file

• HTML search: search always returns nothing when multiple search terms are used and one term is shorter than three characters

2.0.0b2

• #6096: html: Anchor links are not added to figures

• #3620: html: Defer searchindex.js rather than loading it via ajax

• #6113: html: Table cells and list items have large margins

• #5508: linenothreshold option for highlight directive was ignored

• texinfo: make install-info causes syntax error

• texinfo: make install-info fails on macOS

• #3079: texinfo: image files are not copied on make install-info

• #5391: A cross reference in heading is rendered as literal

• #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)

• #6147: classes attribute of citation_reference node is lost

• AssertionError is raised when custom citation_reference node having classes attribute refers missing citation (refs: #6147)

• #2155: Support code directive

• C++, fix parsing of braced initializers.

• #6172: AttributeError is raised for old styled index nodes

• #4872: inheritance_diagram: correctly describe behavior of parts option in docs, allow negative values.

• #6178: i18n: Captions missing in translations for hidden TOCs

2.0.0 final

• #6196: py domain: unexpected prefix is generated

测试

2.0.0b1

• Stop to use SPHINX_TEST_TEMPDIR envvar

2.0.0b2

• Add a helper function: sphinx.testing.restructuredtext.parse()

版本 1.8.5 (2019年3月10日)

修正了错误

• LaTeX: Remove extraneous space after author names on PDF title page (refs: #6004)

• #6026: LaTeX: A cross reference to definition list does not work

• #6046: LaTeX: TypeError is raised when invalid latex_elements given

• #6067: LaTeX: images having a target are concatenated to next line

• #6067: LaTeX: images having a target are not aligned even if specified

• #6149: LaTeX: :index: role in titles causes Use of \@icentercr doesn't match its definition error on latexpdf build

• #6019: imgconverter: Including multipage PDF fails

• #6047: autodoc: autofunction emits a warning for method objects

• #6028: graphviz: Ensure the graphviz filenames are reproducible

• #6068: doctest: skipif option may remove the code block from documentation

• #6136: :name: option for math directive causes a crash

• #6139: intersphinx: ValueError on failure reporting

• #6135: changes: Fix UnboundLocalError when any module found

• #3859: manpage: code-block captions are not displayed correctly

版本 1.8.4 (2019年2月3日)

修正了错误

• #3707: latex: no bold checkmark (✔) available.

• #5605: with the documentation language set to Chinese, English words could not be searched.

• #5889: LaTeX: user numfig_format is stripped of spaces and may cause build failure

• C++, fix hyperlinks for declarations involving east cv-qualifiers.

• #5755: C++, fix duplicate declaration error on function templates with constraints in the return type.

• C++, parse unary right fold expressions and binary fold expressions.

• pycode could not handle egg files on windows

• #5928: KeyError: ‘DOCUTILSCONFIG’ when running build

• #5936: LaTeX: PDF build broken by inclusion of image taller than page height in an admonition

• #5231: “make html” does not read and build “po” files in “locale” dir

• #5954: :scale: image option may break PDF build if image in an admonition

• #5966: mathjax has not been loaded on incremental build

• #5960: LaTeX: modified PDF layout since September 2018 TeXLive update of parskip.sty

• #5948: LaTeX: duplicated labels are generated for sections

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

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

• #5871: texinfo: a section title . is not allowed

版本 1.8.3 (2018年12月26日)

添加功能

• LaTeX: it is possible to insert custom material to appear on back of title page, see discussion of 'maketitle' key of latex_elements ('manual' docclass only)

修正了错误

• #5725: mathjax: Use CDN URL for “latest” version by default

• #5460: html search does not work with some 3rd party themes

• #5520: LaTeX, caption package incompatibility since Sphinx 1.6

• #5614: autodoc: incremental build is broken when builtin modules are imported

• #5627: qthelp: index.html missing in QtHelp

• #5659: linkcheck: crashes for a hyperlink containing multibyte character

• #5754: DOC: Fix some mistakes in LaTeX 定制

• #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since 1.6.6 (refs: #1238)

• #5636: C++, fix parsing of floating point literals.

• #5496 (again): C++, fix assertion in partial builds with duplicates.

• #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty

• #1956: Default conf.py is not PEP8-compliant

• #5849: LaTeX: document class \maketitle is overwritten with no possibility to use original meaning in place of Sphinx custom one

• #5834: apidoc: wrong help for --tocfile

• #5800: todo: crashed if todo is defined in TextElement

• #5846: htmlhelp: convert hex escaping to decimal escaping in .hhc/.hhk files

• htmlhelp: broken .hhk file generated when title contains a double quote

版本 1.8.2 (2018年11月11日)

不兼容的变化

• #5497: Do not include MathJax.js and jsmath.js unless it is really needed

添加功能

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

修正了错误

• #5490: latex: enumerated list causes a crash with recommonmark

• #5492: sphinx-build fails to build docs w/ Python < 3.5.2

• #3704: latex: wrong \label positioning for figures with a legend

• #5496: C++, fix assertion when a symbol is declared more than twice.

• #5493: gettext: crashed with broken template

• #5495: csv-table directive with file option in included file is broken (refs: #4821)

• #5498: autodoc: unable to find type hints for a functools.partial

• #5480: autodoc: unable to find type hints for unresolvable Forward references

• #5419: incompatible math_block node has been generated

• #5548: Fix ensuredir() in case of pre-existing file

• #5549: graphviz Correctly deal with non-existing static dir

• #3002: i18n: multiple footnote_references referring same footnote cause duplicated node_ids

• #5563: latex: footnote_references generated by extension causes a LaTeX builder crash

• #5561: make all-pdf fails with old xindy version

• #5557: quickstart: –no-batchfile isn’t honored

• #3080: texinfo: multiline rubrics are broken

• #3080: texinfo: multiline citations are broken

版本 1.8.1 (2018年9月22日)

不兼容的变化

• LaTeX \pagestyle commands have been moved to the LaTeX template. No changes in PDF, except possibly if \sphinxtableofcontents, which contained them, had been customized in conf.py. (refs: #5455)

修正了错误

• #5418: Incorrect default path for sphinx-build -d/doctrees files

• #5421: autodoc emits deprecation warning for autodoc_default_flags

• #5422: lambda object causes PicklingError on storing environment

• #5417: Sphinx fails to build with syntax error in Python 2.7.5

• #4911: add latexpdf to make.bat for non make-mode

• #5436: Autodoc does not work with enum subclasses with properties/methods

• #5437: autodoc: crashed on modules importing eggs

• #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’

• #5431: autodoc: autofunction emits a warning for callable objects

• #5457: Fix TypeError in error message when override is prohibited

• #5453: PDF builds of ‘howto’ documents have no page numbers

• #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0

• #5454: latex: Index has disappeared from PDF for Japanese documents

• #5432: py domain: :type: field can’t process :term: references

• #5426: py domain: TypeError has been raised for class attribute

版本 1.8.0 (2018年9月13日)

依赖

1.8.0b1

• LaTeX: latex_use_xindy, if True (default for xelatex/lualatex), instructs make latexpdf to use xindy for general index. Make sure your LaTeX distribution includes it. (refs: #5134)

• LaTeX: latexmk is required for make latexpdf on Windows

不兼容的变化

1.8.0b2

• #5282: html theme: refer pygments_style settings of HTML themes preferentially

• The URL of download files are changed

• #5127: quickstart: Makefile and make.bat are not overwritten if exists

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: extensions which stores any data to environment should return the version of its env data structure as metadata. In detail, please see 扩展元数据.

• Sphinx expects source parser modules to have supported file formats as Parser.supported attribute

• The default value of epub_author and epub_publisher are changed from 'unknown' to the value of author. This is same as a conf.py file sphinx-build generates.

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

• The processing order on reading phase is changed. smart_quotes, sphinx domains, doctree-read event and versioning doctrees are invoked earlier than so far. For more details, please read a description of Sphinx.add_transform()

• #4827: All substitution_definition nodes are removed from doctree on reading phase

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

• #789: :samp: role supports to escape curly braces with backslash

• #4811: The files under html_static_path are excluded from source files.

• latex: Use \sphinxcite for citation references instead \hyperref

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

• #1857: latex: latex_show_pagerefs does not add pagerefs for citations

• #4648: latex: Now “rubric” elements are rendered as unnumbered section title

• #4983: html: The anchor for productionlist tokens has been changed

• Modifying a template variable script_files in templates is allowed now. Please use app.add_js_file() instead.

• #5072: 仅使用新文档保存环境对象

• #5035: qthelp builder allows dashes in :confval:`qthelp_names