Sphinx

# Sphinx 1.7

## Release 1.7.9 (released Sep 05, 2018)

### Features added

- #5359: Make generated texinfo files reproducible by sorting the anchors

### Bugs fixed

- #5361: crashed on incremental build if document uses include directive

## Release 1.7.8 (released Aug 29, 2018)

### Incompatible changes

- The type of `env.included` has been changed to dict of set

### Bugs fixed

- #5320: intersphinx: crashed if invalid url given

- #5326: manpage: crashed when invalid docname is specified as `man_pages`

- #5322: autodoc: `Any` typehint causes formatting error

- #5327: “document isn’t included in any toctree” warning on rebuild with generated files

- #5335: quickstart: escape sequence has been displayed with MacPorts’ python

## Release 1.7.7 (released Aug 19, 2018)

### Bugs fixed

- #5198: document not in toctree warning when including files only for parallel builds

- LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings in latex console output (refs: #5236)

- LaTeX: suppress “remreset Warning: The remreset package is obsolete” in latex console output with recent LaTeX (refs: #5237)

- #5234: PDF output: usage of PAPER environment variable is broken since Sphinx 1.5

- LaTeX: fix the `latex_engine` documentation regarding Latin Modern font with XeLaTeX/LuaLateX (refs: #5251)

- #5280: autodoc: Fix wrong type annotations for complex typing

- autodoc: Optional types are wrongly rendered

- #5291: autodoc crashed by ForwardRef types

- #5211: autodoc: No docs generated for functools.partial functions

- #5306: autodoc: `getargspec()` raises NameError for invalid typehints

- #5298: imgmath: math_number_all causes equations to have two numbers in html

- #5294: sphinx-quickstart blank prompts in PowerShell

## Release 1.7.6 (released Jul 17, 2018)

### Bugs fixed

- #5037: LaTeX `\sphinxupquote{}` breaks in Russian

- sphinx.testing uses deprecated pytest API; `Node.get_marker(name)`

- #5016: crashed when recommonmark.AutoStrictify is enabled

- #5022: latex: crashed with Docutils package provided by Debian/Ubuntu

- #5009: latex: a label for table is vanished if table does not have a caption

- #5048: crashed with numbered toctree

- #2410: C, render empty argument lists for macros.

- C++, fix lookup of full template specializations with no template arguments.

- #4667: C++, fix assertion on missing references in global scope when using intersphinx. Thanks to Alan M. Carroll.

- #5019: autodoc: crashed by Form Feed Character

- #5032: autodoc: loses the first staticmethod parameter for old styled classes

- #5036: quickstart: Typing Ctrl-U clears the whole of line

- #5066: html: “relations” sidebar is not shown by default

- #5091: latex: curly braces in index entries are not handled correctly

- #5070: epub: Wrong internal href fragment links

- #5104: apidoc: Interface of `sphinx.apidoc:main()` has changed

- #4272: PDF builds of French projects have issues with XeTeX

- #5076: napoleon raises RuntimeError with python 3.7

- #5125: sphinx-build: Interface of `sphinx:main()` has changed

- sphinx-build: `sphinx.cmd.build.main()` refers `sys.argv` instead of given argument

- #5146: autosummary: warning is emitted when the first line of docstring ends with literal notation

- autosummary: warnings of autosummary indicates wrong location (refs: #5146)

- #5143: autodoc: crashed on inspecting dict like object which does not support sorting

- #5139: autodoc: Enum argument missing if it shares value with another

- #4946: py domain: rtype field could not handle “`None`” as a type

- #5176: LaTeX: indexing of terms containing `@`, `!`, or `"` fails

- #5161: html: crashes if copying static files are failed

- #5167: autodoc: Fix formatting type annotations for tuples with more than two arguments

- #3329: i18n: crashed by auto-symbol footnote references

- #5158: autosummary: module summary has been broken when it starts with heading

## Release 1.7.5 (released May 29, 2018)

### Bugs fixed

- #4924: html search: Upper characters problem in any other languages

- #4932: apidoc: some subpackage is ignored if sibling subpackage contains a module starting with underscore

- #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used for contents, topic, admonition, table and section.

- #4913: i18n: literal blocks in bullet list are not translated

- #4962: C++, raised TypeError on duplicate declaration.

- #4825: C++, properly parse expr roles and give better error messages when (escaped) line breaks are present.

- C++, properly use `desc_addname` nodes for prefixes of names.

- C++, parse pack expansions in function calls.

- #4915, #4916: links on search page are broken when using dirhtml builder

- #4969: autodoc: constructor method should not have return annotation

- latex: deeply nested enumerated list which is beginning with non-1 causes LaTeX engine crashed

- #4978: latex: shorthandoff is not set up for Brazil locale

- #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/

- #4946: py domain: type field could not handle “`None`” as a type

- #4979: latex: Incorrect escaping of curly braces in index entries

- #4956: autodoc: Failed to extract document from a subclass of the class on mocked module

- #4973: latex: glossary directive adds whitespace to each item

- #4980: latex: Explicit labels on code blocks are duplicated

- #4919: node.asdom() crashes if toctree has :numbered: option

- #4914: autodoc: Parsing error when using dataclasses without default values

- #4931: autodoc: crashed when handler for autodoc-skip-member raises an error

- #4931: autodoc: crashed when subclass of mocked class are processed by napoleon module

- #5007: sphinx-build crashes when error log contains a “%” character

## Release 1.7.4 (released Apr 25, 2018)

### Bugs fixed

- #4885, #4887: domains: Crashed with duplicated objects

- #4889: latex: sphinx.writers.latex causes recursive import

## Release 1.7.3 (released Apr 23, 2018)

### Bugs fixed

- #4769: autodoc loses the first staticmethod parameter

- #4790: autosummary: too wide two column tables in PDF builds

- #4795: Latex customization via `_templates/longtable.tex_t` is broken

- #4789: imgconverter: confused by convert.exe of Windows

- #4783: On windows, Sphinx crashed when drives of srcdir and outdir are different

- #4812: autodoc ignores type annotated variables

- #4817: wrong URLs on warning messages

- #4784: latex: `latex_show_urls` assigns incorrect footnote numbers if hyperlinks exists inside substitutions

- #4837: latex with class memoir Error: Font command `\sf` is not supported

- #4803: latex: too slow in proportion to number of auto numbered footnotes

- #4838: htmlhelp: The entries in .hhp file is not ordered

- toctree directive tries to glob for URL having query_string

- #4871: html search: Upper characters problem in German

- #4717: latex: Compilation for German docs failed with LuaLaTeX and XeLaTeX

- #4459: duplicated labels detector does not work well in parallel build

- #4878: Crashed with extension which returns invalid metadata

## Release 1.7.2 (released Mar 21, 2018)

### Incompatible changes

- #4520: apidoc: folders with an empty __init__.py are no longer excluded from TOC

### Bugs fixed

- #4669: sphinx.build_main and sphinx.make_main throw NameError

- #4685: autosummary emits meaningless warnings

- autodoc: crashed when invalid options given

- pydomain: always strip parenthesis if empty (refs: #1042)

- #4689: autosummary: unexpectedly strips docstrings containing “i.e.”

- #4701: viewcode: Misplaced `<div>` in viewcode html output

- #4444: Don’t require numfig to use :numref: on sections

- #4727: Option clash for package textcomp

- #4725: Sphinx does not work with python 3.5.0 and 3.5.1

- #4716: Generation PDF file with TexLive on Windows, file not found error

- #4574: vertical space before equation in latex

- #4720: message when an image is mismatched for builder is not clear

- #4655, #4684: Incomplete localization strings in Polish and Chinese

- #2286: Sphinx crashes when error is happens in rendering HTML pages

- #4688: Error to download remote images having long URL

- #4754: sphinx/pycode/__init__.py raises AttributeError

- #1435: qthelp builder should htmlescape keywords

- epub: Fix docTitle elements of toc.ncx is not escaped

- #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed

- #4767: html: search highlighting breaks mathjax equations

## Release 1.7.1 (released Feb 23, 2018)

### Deprecated

- #4623: `sphinx.build_main()` is deprecated.

- autosummary: The interface of `sphinx.ext.autosummary.get_documenter()` has been changed (Since 1.7.0)

- #4664: `sphinx.ext.intersphinx.debug()` is deprecated.

For more details, see deprecation APIs list.

### Bugs fixed

- #4608: epub: Invalid meta tag is generated

- #4260: autodoc: keyword only argument separator is not disappeared if it is appeared at top of the argument list

- #4622: epub: `epub_scheme` does not effect to content.opf

- #4627: graphviz: Fit graphviz images to page

- #4617: quickstart: PROJECT_DIR argument is required

- #4623: sphinx.build_main no longer exists in 1.7.0

- #4615: The argument of `sphinx.build` has been changed in 1.7.0

- autosummary: The interface of `sphinx.ext.autosummary.get_documenter()` has been changed

- #4630: Have order on msgids in sphinx.pot deterministic

- #4563: autosummary: Incorrect end of line punctuation detection

- #4577: Enumerated sublists with explicit start with wrong number

- #4641: A external link in TOC cannot contain “?” with `:glob:` option

- C++, add missing parsing of explicit casts and typeid in expression parsing.

- C++, add missing parsing of `this` in expression parsing.

- #4655: Fix incomplete localization strings in Polish

- #4653: Fix error reporting for parameterless ImportErrors

- #4664: Reading objects.inv fails again

- #4662: `any` refs with `term` targets crash when an ambiguity is encountered

## Release 1.7.0 (released Feb 12, 2018)

### Dependencies

1.7.0b1

- Add `packaging` package

### Incompatible changes

1.7.0b1

- #3668: The arguments has changed of main functions for each command

- #3893: Unknown html_theme_options throw warnings instead of errors

- #3927: Python parameter/variable types should match classes, not all objects

- #3962: sphinx-apidoc now recognizes given directory as an implicit namespace package when `--implicit-namespaces` option given, not subdirectories of given directory.

- #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc

- #4226: apidoc: Generate new style makefile (make-mode)

- #4274: sphinx-build returns 2 as an exit code on argument error

- #4389: output directory will be created after loading extensions

- autodoc does not generate warnings messages to the generated document even if `keep_warnings` is `True`. They are only emitted to stderr.

- shebang line is removed from generated conf.py

- #2557: autodoc: `autodoc_mock_imports` only mocks specified modules with their descendants. It does not mock their ancestors. If you want to mock them, please specify the name of ancestors explicitly.

- #3620: html theme: move DOCUMENTATION_OPTIONS to independent JavaScript file (refs: #4295)

- #4246: Limit width of text body for all themes. Configurable via theme options `body_min_width` and `body_max_width`.

- #4771: apidoc: The `exclude_patterns` arguments are ignored if they are placed just after command line options

1.7.0b2

- #4467: html theme: Rename `csss` block to `css`

### Deprecated

1.7.0b1

- using a string value for `html_sidebars` is deprecated and only list values will be accepted at 2.0.

- `format_annotation()` and `formatargspec()` is deprecated. Please use `sphinx.util.inspect.Signature` instead.

- `sphinx.ext.autodoc.AutodocReporter` is replaced by `sphinx.util.docutils. switch_source_input()` and now deprecated. It will be removed in Sphinx 2.0.

- `sphinx.ext.autodoc.add_documenter()` and `AutoDirective._register` is now deprecated. Please use `app.add_autodocumenter()` instead.

- `AutoDirective._special_attrgetters` is now deprecated. Please use `app.add_autodoc_attrgetter()` instead.

### Features added

1.7.0b1

- C++, handle `decltype(auto)`.

- #2406: C++, add proper parsing of expressions, including linking of identifiers.

- C++, add a `cpp:expr` role for inserting inline C++ expressions or types.

- C++, support explicit member instantiations with shorthand `template` prefix

- C++, make function parameters linkable, like template params.

- #3638: Allow to change a label of reference to equation using `math_eqref_format`

- Now `suppress_warnings` accepts following configurations:

  - `ref.python` (ref: #3866)

- #3872: Add latex key to configure literal blocks caption position in PDF output (refs #3792, #1723)

- In case of missing docstring try to retrieve doc from base classes (ref: #3140)

- #4023: Clarify error message when any role has more than one target.

- #3973: epub: allow to override build date

- #3972: epub: Sort manifest entries by filename

- #4052: viewcode: Sort before highlighting module code

- #1448: qthelp: Add new config value; `qthelp_namespace`

- #4140: html themes: Make body tag inheritable

- #4168: improve zh search with jieba

- HTML themes can set up default sidebars through `theme.conf`

- #3160: html: Use `<kdb>` to represent `:kbd:` role

- #4212: autosummary: catch all exceptions when importing modules

- #4166: Add `math_numfig` for equation numbering by section (refs: #3991, #4080). Thanks to Oliver Jahn.

- #4311: Let LaTeX obey `numfig_secnum_depth` for figures, tables, and code-blocks

- #947: autodoc now supports ignore-module-all to ignore a module’s `__all__`

- #4332: Let LaTeX obey `math_numfig` for equation numbering

- #4093: sphinx-build creates empty directories for unknown targets/builders

- Add `top-classes` option for the `sphinx.ext.inheritance_diagram` extension to limit the scope of inheritance graphs.

- #4183: doctest: `:pyversion:` option also follows PEP-440 specification

- #4235: html: Add `manpages_url` to make manpage roles to hyperlinks

- #3570: autodoc: Do not display ‘typing.’ module for type hints

- #4354: sphinx-build now emits finish message. Builders can modify it through `Builder.epilog` attribute

- #4245: html themes: Add `language` to javascript vars list

- #4079: html: Add `notranslate` class to each code-blocks, literals and maths to let Google Translate know they are not translatable

- #4137: doctest: doctest block is always highlighted as python console (pycon)

- #4137: doctest: testcode block is always highlighted as python

- #3998: text: Assign section numbers by default. You can control it using `text_add_secnumbers` and `text_secnumber_suffix`

1.7.0b2

- #4271: sphinx-build supports an option called `-j auto` to adjust numbers of processes automatically.

- Napoleon: added option to specify custom section tags.

### Features removed

1.7.0b1

- Configuration variables

  - `html_use_smartypants`

  - `latex_keep_old_macro_names`

  - latex_elements[‘footer’]

- utility methods of `sphinx.application.Sphinx` class

  - buildername (property)

  - _display_chunk()

  - old_status_iterator()

  - status_iterator()

  - _directive_helper()

- utility methods of `sphinx.environment.BuildEnvironment` class

  - currmodule (property)

  - currclass (property)

- epub2 builder

- prefix and colorfunc parameter for warn()

- `sphinx.util.compat` module

- `sphinx.util.nodes.process_only_nodes()`

- LaTeX environment `notice`, use `sphinxadmonition` instead

- LaTeX `\sphinxstylethead`, use `\sphinxstyletheadfamily`

- C++, support of function concepts. Thanks to mickk-on-cpp.

- Not used and previously not documented LaTeX macros `\shortversion` and `\setshortversion`

### Bugs fixed

1.7.0b1

- #3882: Update the order of files for HTMLHelp and QTHelp

- #3962: sphinx-apidoc does not recognize implicit namespace packages correctly

- #4094: C++, allow empty template argument lists.

- C++, also hyperlink types in the name of declarations with qualified names.

- C++, do not add index entries for declarations inside concepts.

- C++, support the template disambiguator for dependent names.

- #4314: For PDF ‘howto’ documents, numbering of code-blocks differs from the one of figures and tables

- #4330: PDF ‘howto’ documents have an incoherent default LaTeX tocdepth counter setting

- #4198: autosummary emits multiple ‘autodoc-process-docstring’ event. Thanks to Joel Nothman.

- #4081: Warnings and errors colored the same when building

- latex: Do not display ‘Release’ label if `release` is not set

1.7.0b2

- #4415: autodoc classifies inherited classmethods as regular methods

- #4415: autodoc classifies inherited staticmethods as regular methods

- #4472: DOCUMENTATION_OPTIONS is not defined

- #4491: autodoc: prefer _MockImporter over other importers in sys.meta_path

- #4490: autodoc: type annotation is broken with python 3.7.0a4+

- utils package is no longer installed

- #3952: apidoc: module header is too escaped

- #4275: Formats accepted by sphinx.util.i18n.format_date are limited

- #4493: recommonmark raises AttributeError if AutoStructify enabled

- #4209: intersphinx: In link title, “v” should be optional if target has no version

- #4230: slowdown in writing pages with Sphinx 1.6

- #4522: epub: document is not rebuilt even if config changed

1.7.0b3

- #4019: inheritance_diagram AttributeError stopping make process

- #4531: autosummary: methods are not treated as attributes

- #4538: autodoc: `sphinx.ext.autodoc.Options` has been moved

- #4539: autodoc emits warnings for partialmethods

- #4223: doctest: failing tests reported in wrong file, at wrong line

- i18n: message catalogs are not compiled if specific filenames are given for `sphinx-build` as arguments (refs: #4560)

- #4027: sphinx.ext.autosectionlabel now expects labels to be the same as they are in the raw source; no smart quotes, nothig fancy.

- #4581: apidoc: Excluded modules still included

### Testing

1.7.0b1

- Add support for Docutils 0.14

- Add tests for the `sphinx.ext.inheritance_diagram` extension.