========== 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 :confval:latex_theme_options to override theme options
#7410: Allow to suppress "circular toctree references detected" warnings using :confval:suppress_warnings
C, added scope control directives, :rst:dir:c:namespace, :rst:dir:c:namespace-push, and :rst:dir: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 :confval: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 :confval:globaltoc_collapse and :confval: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 :rst:dir:py:class, :rst:dir:py:exception and :rst:dir:py:method directives
#7596: py domain: Change a type annotation for variables to a hyperlink
#7770: std domain: :rst:dir: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 :confval: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 :confval: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 :confval: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 :confval: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.