Sphinx

# 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()`