Sphinx 2.0

Release 2.0.1 (released Apr 08, 2019)

Bugs fixed

  • LaTeX: some system labels are not translated

  • 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

Release 2.0.0 (released Mar 29, 2019)

Dependencies

2.0.0b1

  • LaTeX builder now depends on TeX Live 2015 or above.

  • LaTeX builder (with 'pdflatex' latex_engine) will process Unicode Greek letters in text (not in math mark-up) via the text font and will not escape them to math mark-up. See the discussion of the 'fontenc' key of latex_elements; such (optional) support for Greek adds, for example on Ubuntu xenial, the texlive-lang-greek and (if default font set-up is not modified) cm-super(-minimal) as additional Sphinx LaTeX requirements.

  • LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' requires (by default) the FreeFont fonts, which in Ubuntu xenial are provided by package fonts-freefont-otf, and e.g. in Fedora 29 via package texlive-gnu-freefont.

  • requests 2.5.0 or above

  • The six package is no longer a dependency

  • The sphinxcontrib-websupport package is no longer a dependency

  • Some packages are separated to sub packages:

    • sphinxcontrib.applehelp

    • sphinxcontrib.devhelp

    • sphinxcontrib.htmlhelp

    • sphinxcontrib.jsmath

    • sphinxcontrib.serializinghtml

    • sphinxcontrib.qthelp

Incompatible changes

2.0.0b1

  • Drop python 2.7 and 3.4 support

  • Drop Docutils 0.11 support

  • Drop features and APIs deprecated in 1.7.x

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

  • LaTeX: Move message resources to 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 Macros.

  • 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

Deprecated

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

For more details, see deprecation APIs list.

Features added

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

Bugs fixed

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

Testing

2.0.0b1

  • Stop to use SPHINX_TEST_TEMPDIR envvar

2.0.0b2

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