Sphinx

# Sphinx 3.1

## Release 3.1.2 (released Jul 05, 2020)

### Incompatible changes

- #7650: autodoc: the signature of base function will be shown for decorated functions, not a signature of decorator

### Bugs fixed

- #7844: autodoc: Failed to detect module when relative module name given

- #7856: autodoc: AttributeError is raised when non-class object is given to the autoclass directive

- #7850: autodoc: KeyError is raised for invalid mark up when autodoc_typehints is ‘description’

- #7812: autodoc: crashed if the target name matches to both an attribute and module that are same name

- #7650: autodoc: function signature becomes `(*args, **kwargs)` if the function is decorated by generic decorator

- #7812: autosummary: generates broken stub files if the target code contains an attribute and module that are same name

- #7806: viewcode: Failed to resolve viewcode references on 3rd party builders

- #7838: html theme: List items have extra vertical space

- #7878: html theme: Undesired interaction between “overflow” and “float”

## Release 3.1.1 (released Jun 14, 2020)

### Incompatible changes

- #7808: napoleon: a type for attribute are represented as typed field

### Features added

- #7807: autodoc: Show detailed warning when type_comment is mismatched with its signature

### Bugs fixed

- #7808: autodoc: Warnings raised on variable and attribute type annotations

- #7802: autodoc: EOFError is raised on parallel build

- #7821: autodoc: TypeError is raised for overloaded C-ext function

- #7805: autodoc: an object which descriptors returns is unexpectedly documented

- #7807: autodoc: wrong signature is shown for the function using contextmanager

- #7812: autosummary: generates broken stub files if the target code contains an attribute and module that are same name

- #7808: napoleon: Warnings raised on variable and attribute type annotations

- #7811: sphinx.util.inspect causes circular import problem

## Release 3.1.0 (released Jun 08, 2020)

### Dependencies

- #7746: mathjax: Update to 2.7.5

### Incompatible changes

- #7477: imgconverter: Invoke “magick convert” command by default on Windows

### Deprecated

- The first argument for sphinx.ext.autosummary.generate.AutosummaryRenderer has been changed to Sphinx object

- `sphinx.ext.autosummary.generate.AutosummaryRenderer` takes an object type as an argument

- The `ignore` argument of `sphinx.ext.autodoc.Documenter.get_doc()`

- The `template_dir` argument of `sphinx.ext.autosummary.generate. AutosummaryRenderer`

- The `module` argument of `sphinx.ext.autosummary.generate. find_autosummary_in_docstring()`

- The `builder` argument of `sphinx.ext.autosummary.generate. generate_autosummary_docs()`

- The `template_dir` argument of `sphinx.ext.autosummary.generate. generate_autosummary_docs()`

- The `ignore` argument of `sphinx.util.docstring.prepare_docstring()`

- `sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()`

- `sphinx.util.rpartition()`

### Features added

- LaTeX: Make the `toplevel_sectioning` setting optional in LaTeX theme

- LaTeX: Allow to override papersize and pointsize from LaTeX themes

- LaTeX: Add `latex_theme_options` to override theme options

- #7410: Allow to suppress “circular toctree references detected” warnings using `suppress_warnings`

- C, added scope control directives, `c:namespace`, `c:namespace-push`, and `c:namespace-pop`.

- #2044: autodoc: Suppress default value for instance attributes

- #7473: autodoc: consider a member public if docstring contains `:meta public:` in info-field-list

- #7487: autodoc: Allow to generate docs for singledispatch functions by py:autofunction

- #7143: autodoc: Support final classes and methods

- #7384: autodoc: Support signatures defined by `__new__()`, metaclasses and builtin base classes

- #2106: autodoc: Support multiple signatures on docstring

- #4422: autodoc: Support GenericAlias in Python 3.7 or above

- #3610: autodoc: Support overloaded functions

- #7722: autodoc: Support TypeVar

- #7466: autosummary: headings in generated documents are not translated

- #7490: autosummary: Add `:caption:` option to autosummary directive to set a caption to the toctree

- #7469: autosummary: Support module attributes

- #248, #6040: autosummary: Add `:recursive:` option to autosummary directive to generate stub files recursively

- #4030: autosummary: Add `autosummary_context` to add template variables for custom templates

- #7530: html: Support nested <kbd> elements

- #7481: html theme: Add right margin to footnote/citation labels

- #7482, #7717: html theme: CSS spacing for code blocks with captions and line numbers

- #7443: html theme: Add new options `globaltoc_collapse` and `globaltoc_includehidden` to control the behavior of globaltoc in sidebar

- #7484: html theme: Avoid clashes between sidebar and other blocks

- #7476: html theme: Relbar breadcrumb should contain current page

- #7506: html theme: A canonical URL is not escaped

- #7533: html theme: Avoid whitespace at the beginning of genindex.html

- #7541: html theme: Add a “clearer” at the end of the “body”

- #7542: html theme: Make admonition/topic/sidebar scrollable

- #7543: html theme: Add top and bottom margins to tables

- #7695: html theme: Add viewport meta tag for basic theme

- #7721: html theme: classic: default codetextcolor/codebgcolor doesn’t override Pygments

- C and C++: allow semicolon in the end of declarations.

- C++, parse parameterized noexcept specifiers.

- #7294: C++, parse expressions with user-defined literals.

- C++, parse trailing return types.

- #7143: py domain: Add `:final:` option to `py:class`, `py:exception` and `py:method` directives

- #7596: py domain: Change a type annotation for variables to a hyperlink

- #7770: std domain: `option` directive support arguments in the form of `foo[=bar]`

- #7582: napoleon: a type for attribute are represented like type annotation

- #7734: napoleon: overescaped trailing underscore on attribute

- #7247: linkcheck: Add `linkcheck_request_headers` to send custom HTTP headers for specific host

- #7792: setuptools: Support `--verbosity` option

- #7683: Add `allowed_exceptions` parameter to `Sphinx.emit()` to allow handlers to raise specified exceptions

- #7295: C++, parse (trailing) requires clauses.

### Bugs fixed

- #6703: autodoc: incremental build does not work for imported objects

- #7564: autodoc: annotations not to be shown for descriptors

- #6588: autodoc: Decorated inherited method has no documentation

- #7469: autodoc: The change of autodoc-process-docstring for variables is cached unexpectedly

- #7559: autodoc: misdetects a sync function is async

- #6857: autodoc: failed to detect a classmethod on Enum class

- #7562: autodoc: a typehint contains spaces is wrongly rendered under `autodoc_typehints``='description'` mode

- #7551: autodoc: failed to import nested class

- #7362: autodoc: does not render correct signatures for built-in functions

- #7654: autodoc: `Optional[Union[foo, bar]]` is presented as `Union[foo, bar, None]`

- #7629: autodoc: autofunction emits an unfriendly warning if an invalid object specified

- #7650: autodoc: undecorated signature is shown for decorated functions

- #7676: autodoc: typo in the default value of autodoc_member_order

- #7676: autodoc: wrong value for :member-order: option is ignored silently

- #7676: autodoc: member-order=”bysource” does not work for C module

- #3673: autodoc: member-order=”bysource” does not work for a module having `__all__`

- #7668: autodoc: wrong retann value is passed to a handler of autodoc-process-signature

- #7711: autodoc: fails with ValueError when processing numpy objects

- #7791: autodoc: TypeError is raised on documenting singledispatch function

- #7551: autosummary: a nested class is indexed as non-nested class

- #7661: autosummary: autosummary directive emits warnings twices if failed to import the target module

- #7685: autosummary: The template variable “members” contains imported members even if `autossummary_imported_members` is `False`

- #7671: autosummary: The location of import failure warning is missing

- #7535: sphinx-autogen: crashes when custom template uses inheritance

- #7536: sphinx-autogen: crashes when template uses i18n feature

- #7781: sphinx-build: Wrong error message when outdir is not directory

- #7653: sphinx-quickstart: Fix multiple directory creation for nested relpath

- #2785: html: Bad alignment of equation links

- #7718: html theme: some themes does not respect background color of Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and traditional)

- #7544: html theme: inconsistent padding in admonitions

- #7581: napoleon: bad parsing of inline code in attribute docstrings

- #7628: imgconverter: runs imagemagick once unnecessary for builders not supporting images

- #7610: incorrectly renders consecutive backslashes for Docutils 0.16

- #7646: handle errors on event handlers

- #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese documents

- #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated labels

- #7723: LaTeX: pdflatex crashed when URL contains a single quote

- #7756: py domain: The default value for positional only argument is not shown

- #7760: coverage: Add `coverage_show_missing_items` to show coverage result to console

- C++, fix rendering and xrefs in nested names explicitly starting in global scope, e.g., `::A::B`.

- C, fix rendering and xrefs in nested names explicitly starting in global scope, e.g., `.A.B`.

- #7763: C and C++, don’t crash during display stringification of unary expressions and fold expressions.