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.