Sphinx

# Sphinx 1.8

## Release 1.8.6 (released Nov 18, 2021)

### Dependencies

- #9807: Restrict Docutils to 0.17.x or older

## Release 1.8.5 (released Mar 10, 2019)

### Bugs fixed

- 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

## Release 1.8.4 (released Feb 03, 2019)

### Bugs fixed

- #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 directive causes crash with Python 3.5.0

- #5995: autodoc: autodoc_mock_imports conflict with metaclass on Python 3.7

- #5871: texinfo: a section title `.` is not allowed

## Release 1.8.3 (released Dec 26, 2018)

### Features added

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

### Bugs fixed

- #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 customization

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

## Release 1.8.2 (released Nov 11, 2018)

### Incompatible changes

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

### Features added

- #5471: Show appropriate deprecation warnings

### Bugs fixed

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

## Release 1.8.1 (released Sep 22, 2018)

### Incompatible changes

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

### Bugs fixed

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

## Release 1.8.0 (released Sep 13, 2018)

### Dependencies

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

### Incompatible changes

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 Extension metadata.

- 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: Save environment object also with only new documents

- #5035: qthelp builder allows dashes in `qthelp_namespace`

- LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able replacement of makeindex (refs: #5134). After upgrading Sphinx, please clean latex build repertory of existing project before new build.

- #5163: html: hlist items are now aligned to top

- `highlightlang` directive is processed on resolving phase

- #4000: LaTeX: template changed. Following elements moved to it:

  - `\begin{document}`

  - `shorthandoff` variable

  - `maketitle` variable

  - `tableofcontents` variable

### Deprecated

1.8.0b2

- `sphinx.io.SphinxI18nReader.set_lineno_for_reporter()` is deprecated

- `sphinx.io.SphinxI18nReader.line` is deprecated

- `sphinx.util.i18n.find_catalog_source_file()` has changed; the gettext_compact argument has been deprecated

- #5403: `sphinx.util.images.guess_mimetype()` has changed; the content argument has been deprecated

1.8.0b1

- `source_parsers` is deprecated

- `autodoc_default_flags` is deprecated

- quickstart: `--epub` option becomes default, so it is deprecated

- Drop function based directive support. For now, Sphinx only supports class based directives (see `Directive`)

- `sphinx.util.docutils.directive_helper()` is deprecated

- `sphinx.cmdline` is deprecated

- `sphinx.make_mode` is deprecated

- `sphinx.locale.l_()` is deprecated

- #2157: helper function `warn()` for HTML themes is deprecated

- `app.override_domain()` is deprecated

- `app.add_stylesheet()` is deprecated

- `app.add_javascript()` is deprecated

- `app.import_object()` is deprecated

- `app.add_source_parser()` has changed; the suffix argument has been deprecated

- `sphinx.versioning.prepare()` is deprecated

- `Config.__init__()` has changed; the dirname, filename and tags argument has been deprecated

- `Config.check_types()` is deprecated

- `Config.check_unicode()` is deprecated

- `sphinx.application.CONFIG_FILENAME` is deprecated

- `highlightlang` directive is deprecated

- `BuildEnvironment.load()` is deprecated

- `BuildEnvironment.loads()` is deprecated

- `BuildEnvironment.frompickle()` is deprecated

- `env.read_doc()` is deprecated

- `env.update()` is deprecated

- `env._read_serial()` is deprecated

- `env._read_parallel()` is deprecated

- `env.write_doctree()` is deprecated

- `env._nitpick_ignore` is deprecated

- `env.versionchanges` is deprecated

- `env.dump()` is deprecated

- `env.dumps()` is deprecated

- `env.topickle()` is deprecated

- `env.note_versionchange()` is deprecated

- `sphinx.writers.latex.Table.caption_footnotetexts` is deprecated

- `sphinx.writers.latex.Table.header_footnotetexts` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.footnotestack` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.in_container_literal_block` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.next_section_ids` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.restrict_footnote()` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.check_latex_elements()` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.bibitems` is deprecated

- `sphinx.writers.latex.LaTeXTranslator.hlsettingstack` is deprecated

- `sphinx.writers.latex.ExtBabel.get_shorthandoff()` is deprecated

- `sphinx.writers.html.HTMLTranslator.highlightlang` is deprecated

- `sphinx.writers.html.HTMLTranslator.highlightlang_base` is deprecated

- `sphinx.writers.html.HTMLTranslator.highlightlangopts` is deprecated

- `sphinx.writers.html.HTMLTranslator.highlightlinenothreshold` is deprecated

- `sphinx.writers.html5.HTMLTranslator.highlightlang` is deprecated

- `sphinx.writers.html5.HTMLTranslator.highlightlang_base` is deprecated

- `sphinx.writers.html5.HTMLTranslator.highlightlangopts` is deprecated

- `sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold` is deprecated

- `sphinx.ext.mathbase` extension is deprecated

- `sphinx.ext.mathbase.math` node is deprecated

- `sphinx.ext.mathbase.displaymath` node is deprecated

- `sphinx.ext.mathbase.eqref` node is deprecated

- `sphinx.ext.mathbase.is_in_section_title()` is deprecated

- `sphinx.ext.mathbase.MathDomain` is deprecated

- `sphinx.ext.mathbase.MathDirective` is deprecated

- `sphinx.ext.mathbase.math_role` is deprecated

- `sphinx.ext.mathbase.setup_math()` is deprecated

- `sphinx.directives.other.VersionChanges` is deprecated

- `sphinx.highlighting.PygmentsBridge.unhighlight()` is deprecated

- `sphinx.ext.mathbase.get_node_equation_number()` is deprecated

- `sphinx.ext.mathbase.wrap_displaymath()` is deprecated

- The `trim_doctest_flags` argument of `sphinx.highlighting.PygmentsBridge` is deprecated

For more details, see deprecation APIs list.

### Features added

1.8.0b2

- #5388: Ensure frozen object descriptions are reproducible

- #5362: apidoc: Add `--tocfile` option to change the filename of ToC

1.8.0b1

- Add `config-inited` event

- Add `sphinx.config.Any` to represent the config value accepts any type of value

- `source_suffix` allows a mapping fileext to file types

- Add `author` as a configuration value

- #2852: imgconverter: Support to convert GIF to PNG

- `sphinx-build` command supports i18n console output

- Add `app.add_message_catalog()` and `sphinx.locale.get_translations()` to support translation for 3rd party extensions

- helper function `warning()` for HTML themes is added

- Add `Domain.enumerable_nodes` to manage own enumerable nodes for domains (experimental)

- Add a new keyword argument `override` to Application APIs

- LaTeX: new key `'fvset'` for `latex_elements`. For XeLaTeX/LuaLaTeX its default sets `fanvyvrb` to use normal, not small, fontsize in code-blocks (refs: #4793)

- Add `html_css_files` and `epub_css_files` for adding CSS files from configuration

- Add `html_js_files` for adding JS files from configuration

- #4834: Ensure set object descriptions are reproducible.

- #4828: Allow to override `numfig_format` partially. Full definition is not needed.

- Improve warning messages during including (refs: #4818)

- LaTeX: separate customizability of `guilabel` and `menuselection` (refs: #4830)

- Add `Config.read()` classmethod to create a new config object from configuration file

- #4866: Wrap graphviz diagrams in `<div>` tag

- viewcode: Add `viewcode-find-source` and `viewcode-follow-imported` to load source code without loading

- #4785: napoleon: Add strings to translation file for localisation

- #4927: Display a warning when invalid values are passed to linenothreshold option of highlight directive

- C++:

  - Add a `cpp:texpr` role as a sibling to `cpp:expr`.

  - Add support for unions.

  - #3593, #2683: add support for anonymous entities using names staring with `@`.

  - #5147: add support for (most) character literals.

  - Cross-referencing entities inside primary templates is supported, and now properly documented.

  - #1552: add new cross-referencing format for `cpp:any` and `cpp:func` roles, for referencing specific function overloads.

- #3606: MathJax should be loaded with async attribute

- html: Output `canonical_url` metadata if `html_baseurl` set (refs: #4193)

- #5029: autosummary: expose `inherited_members` to template

- #3784: mathjax: Add `mathjax_options` to give options to script tag for mathjax

- #726, #969: mathjax: Add `mathjax_config` to give in-line configurations for mathjax

- #4362: latex: Don’t overwrite .tex file if document not changed

- #1431: latex: Add alphanumeric enumerated list support

- Add `latex_use_xindy` for UTF-8 savvy indexing, defaults to `True` if `latex_engine` is `'xelatex'` or `'lualatex'`. (refs: #5134, #5192, #5212)

- #4976: `SphinxLoggerAdapter.info()` now supports `location` parameter

- #5122: setuptools: support nitpicky option

- #2820: autoclass directive supports nested class

- Add `app.add_html_math_renderer()` to register a math renderer for HTML

- Apply `trim_doctest_flags` to all builders (cf. text, manpages)

- #5140: linkcheck: Add better Accept header to HTTP client

- #4614: sphinx-build: Add `--keep-going` option to show all warnings

- Add `math:numref` role to refer equations (Same as `eq`)

- quickstart: epub builder is enabled by default

- #5246: Add `singlehtml_sidebars` to configure sidebars for singlehtml builder

- #5273: doctest: Skip doctest conditionally

- #5306: autodoc: emit a warning for invalid typehints

- #4075, #5215: autodoc: Add `autodoc_default_options` which accepts option values as dict

### Bugs fixed

1.8.0b2

- html: search box overrides to other elements if scrolled

- i18n: warnings for translation catalogs have wrong line numbers (refs: #5321)

- #5325: latex: cross references has been broken by multiply labeled objects

- C++, fixes for symbol addition and lookup. Lookup should no longer break in partial builds. See also #5337.

- #5348: download reference to remote file is not displayed

- #5282: html theme: `pygments_style` of theme was overridden by `conf.py` by default

- #4379: toctree shows confusing warning when document is excluded

- #2401: autodoc: `:members:` causes `:special-members:` not to be shown

- autodoc: ImportError is replaced by AttributeError for deeper module

- #2720, #4034: Incorrect links with `:download:`, duplicate names, and parallel builds

- #5290: autodoc: failed to analyze source code in egg package

- #5399: Sphinx crashes if unknown po file exists

1.8.0b1

- i18n: message catalogs were reset on each initialization

- #4850: latex: footnote inside footnote was not rendered

- #4945: i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks to Shengjing Zhu.

- #4983: productionlist directive generates invalid IDs for the tokens

- #5132: lualatex: PDF build fails if indexed word starts with Unicode character

- #5133: latex: index headings “Symbols” and “Numbers” not internationalized

- #5114: sphinx-build: Handle errors on scanning documents

- epub: spine has been broken when “self” is listed on toctree (refs: #4611)

- #344: autosummary does not understand docstring of module level attributes

- #5191: C++, prevent nested declarations in functions to avoid lookup problems.

- #5126: C++, add missing isPack method for certain template parameter types.

- #5187: C++, parse attributes on declarators as well.

- C++, parse delete expressions and basic new expressions as well.

- #5002: graphviz: SVGs do not adapt to the column width

### Features removed

1.8.0b1

- `sphinx.ext.pngmath` extension

### Documentation

1.8.0b1

- #5083: Fix wrong make.bat option for internationalization.

- #5115: napoleon: add admonitions added by #4613 to the docs.