Sphinx 2.0.0 (2019-03-28)

See also

Dependencies

  • 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

  • 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

Features added

  • #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`