From Get docs


Release 4.2.0 (in development)


Incompatible changes


Features added

Bugs fixed


Release 4.1.2 (in development)


Incompatible changes


Features added

Bugs fixed


Release 4.1.1 (released Jul 15, 2021)


  • #9434: sphinxcontrib-htmlhelp-2.0.0 or above
  • #9434: sphinxcontrib-serializinghtml-1.1.5 or above

Bugs fixed

  • #9438: html: HTML logo or Favicon specified as file not being found on output

Release 4.1.0 (released Jul 12, 2021)


  • Support jinja2-3.0


  • The app argument of sphinx.environment.BuildEnvironment becomes required
  • sphinx.application.Sphinx.html_theme
  • sphinx.ext.autosummary._app
  • sphinx.util.docstrings.extract_metadata()

Features added

  • #8107: autodoc: Add class-doc-from option to autoclass directive to control the content of the specific class like autoclass_content
  • #8588: autodoc: autodoc_type_aliases now supports dotted name. It allows you to define an alias for a class with module name like
  • #9175: autodoc: Special member is not documented in the module
  • #9195: autodoc: The arguments of typing.Literal are wrongly rendered
  • #9185: autodoc: autodoc_typehints allows 'both' setting to allow typehints to be included both in the signature and description
  • #4257: autodoc: Add autodoc_class_signature to separate the class entry and the definition of __init__() method
  • #8061, #9218: autodoc: Support variable comment for alias classes
  • #3014: autodoc: Add autodoc-process-bases to modify the base classes of the class definitions
  • #9272: autodoc: Render enum values for the default argument value better
  • #9384: autodoc: autodoc_typehints='none' now erases typehints for variables, attributes and properties
  • #3257: autosummary: Support instance attributes for classes
  • #9358: html: Add “heading” role to the toctree items
  • #9225: html: Add span tag to the return typehint of method/function
  • #9129: html search: Show search summaries when html_copy_source = False
  • #9307: html search: Prevent corrections and completions in search field
  • #9120: html theme: Eliminate prompt characters of code-block from copyable text
  • #9176: i18n: Emit a debug message if message catalog file not found under locale_dirs
  • #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese documents
  • #9016: linkcheck: Support checking anchors on
  • #9016: linkcheck: Add a new event linkcheck-process-uri to modify URIs before checking hyperlinks
  • #6525: linkcheck: Add linkcheck_allowed_redirects to mark hyperlinks that are redirected to expected URLs as “working”
  • #1874: py domain: Support union types using | in info-field-list
  • #9268: py domain: python_use_unqualified_type_names supports type field in info-field-list
  • #9097: Optimize the parallel build
  • #9131: Add nitpick_ignore_regex to ignore nitpicky warnings using regular expressions
  • #9174: Add Sphinx.set_html_assets_policy to tell extensions to include HTML assets in all the pages. Extensions can check this via Sphinx.registry.html_assets_policy
  • C++, add support for
    • inline variables,
    • consteval functions,
    • constinit variables,
    • char8_t,
    • explicit() specifier,
    • digit separators in literals, and
    • constraints in placeholder type specifiers, aka. adjective syntax (e.g., Sortable auto &v).
  • C, add support for digit separators in literals.
  • #9166: LaTeX: support containers in LaTeX output

Bugs fixed

  • #8872: autodoc: stacked singledispatches are wrongly rendered
  • #8597: autodoc: a docsting having metadata only should be treated as undocumented
  • #9185: autodoc: typehints for overloaded functions and methods are inaccurate
  • #9250: autodoc: The inherited method not having docstring is wrongly parsed
  • #9283: autodoc: autoattribute directive failed to generate document for an attribute not having any comment
  • #9364: autodoc: single element tuple on the default argument value is wrongly rendered
  • #9362: autodoc: AttributeError is raised on processing a subclass of Tuple[()]
  • #9404: autodoc: TypeError is raised on processing dict-like object (not a class) via autoclass directive
  • #9317: html: Pushing left key causes visiting the next page at the first page
  • #9381: html: URL for html_favicon and html_log does not work
  • #9270: html theme : pyramid theme generates incorrect logo links
  • #9217: manpage: The name of manpage directory that is generated by man_make_section_directory is not correct
  • #9350: manpage: Fix font isn’t reset after keyword at the top of samp role
  • #9306: Linkcheck reports broken link when remote server closes the connection on HEAD request
  • #9280: py domain: “exceptions” module is not displayed
  • #9418: py domain: a Callable annotation with no parameters (e.g. Callable[[], None]) will be rendered with a bracket missing (Callable[], None])
  • #9319: quickstart: Make sphinx-quickstart exit when already exists
  • #9387: xml: XML Builder ignores custom visitors
  • #9224: :param: and :type: fields does not support a type containing whitespace (ex. Dict[str, str])
  • #8945: when transforming typed fields, call the specified role instead of making an single xref. For C and C++, use the expr role for typed fields.

Release 4.0.3 (released Jul 05, 2021)

Features added

  • C, add C23 keywords _Decimal32, _Decimal64, and _Decimal128.
  • #9354: C, add c_extra_keywords to allow user-defined keywords during parsing.
  • Revert the removal of sphinx.util:force_decode() to become some 3rd party extensions available again during 5.0

Bugs fixed

  • #9330: changeset domain: versionchanged with contents being a list will cause error during pdf build
  • #9313: LaTeX: complex table with merged cells broken since 4.0
  • #9305: LaTeX: backslash may cause Improper discretionary list pdf build error with Japanese engines
  • #9354: C, remove special macro names from the keyword list. See also c_extra_keywords.
  • #9322: KeyError is raised on PropagateDescDomain transform

Release 4.0.2 (released May 20, 2021)


  • #9216: Support jinja2-3.0

Incompatible changes

  • #9222: Update Underscore.js to 1.13.1
  • #9217: manpage: Stop creating a section directory on build manpage by default (see man_make_section_directory)

Bugs fixed

  • #9210: viewcode: crashed if non importable modules found on parallel build
  • #9240: Unknown node error for pending_xref_condition is raised if an extension that does not support the node installs a missing-reference handler

Release 4.0.1 (released May 11, 2021)

Bugs fixed

  • #9189: autodoc: crashed when ValueError is raised on generating signature from a property of the class
  • #9188: autosummary: warning is emitted if list value is set to autosummary_generate
  • #8380: html search: tags for search result are broken
  • #9198: i18n: Babel emits errors when running compile_catalog
  • #9205: py domain: The :canonical: option causes “more than one target for cross-reference” warning
  • #9201: websupport: UndefinedError is raised: ‘css_tag’ is undefined

Release 4.0.0 (released May 09, 2021)



  • Drop python 3.5 support
  • Drop docutils 0.12 and 0.13 support
  • LaTeX: add tex-gyre font dependency


  • Support docutils-0.17. Please notice it changes the output of HTML builder. Some themes do not support it, and you need to update your custom CSS to upgrade it.

Incompatible changes


  • #8539: autodoc: info-field-list is generated into the class description when autodoc_typehints='description' and autoclass_content='class' set

  • #8898: extlinks: “%s” becomes required keyword in the link caption string

  • domain: The Index class becomes subclasses of abc.ABC to indicate methods that must be overrided in the concrete classes

  • #4826: py domain: The structure of python objects is changed. A boolean value is added to indicate that the python object is canonical one

  • #7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom MathJax configuration may have to set the old MathJax path or update their configuration for version 3. See sphinx.ext.mathjax.

  • #7784: i18n: The msgid for alt text of image is changed

  • #5560: napoleon: napoleon_use_param also affect “other parameters” section

  • #7996: manpage: Make a section directory on build manpage by default (see man_make_section_directory)

  • #7849: html: Change the default setting of html_codeblock_linenos_style to 'inline'

  • #8380: html search: search results are wrapped with

    instead of

    html theme: Move a script tag for documentation_options.js in basic/layout.html to script_files variable

    html theme: Move CSS tags in basic/layout.html to css_files variable

    #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older

    #8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese documents

    #5977: py domain: :var:, :cvar: and :ivar: fields do not create cross-references

    #4550: The align attribute of figure and table nodes becomes None by default instead of 'default'

    #8769: LaTeX refactoring: split sphinx.sty into multiple files and rename some auxiliary files created in latex build output repertory

    #8937: Use explicit title instead of

    #8487: The :file: option for csv-table directive now recognizes an absolute path as a relative path from source directory



    • html_codeblock_linenos_style

    • favicon and logo variable in HTML templates

    • sphinx.directives.patches.CSVTable

    • sphinx.directives.patches.ListTable

    • sphinx.directives.patches.RSTTable

    • sphinx.ext.autodoc.directive.DocumenterBridge.filename_set

    • sphinx.ext.autodoc.directive.DocumenterBridge.warn()

    • sphinx.registry.SphinxComponentRegistry.get_source_input()

    • sphinx.registry.SphinxComponentRegistry.source_inputs

    • sphinx.transforms.FigureAligner

    • sphinx.util.pycompat.convert_with_2to3()

    • sphinx.util.pycompat.execfile_()

    • sphinx.util.smartypants

    • sphinx.util.typing.DirectiveOption

    Features added


    • #8924: autodoc: Support bound argument for TypeVar

    • #7383: autodoc: Support typehints for properties

    • #5603: autodoc: Allow to refer to a python class using its canonical name when the class has two different names; a canonical name and an alias name

    • #8539: autodoc: Add autodoc_typehints_description_target to control the behavior of autodoc_typehints=description

    • #8841: autodoc: autodoc_docstring_signature will continue to look for multiple signature lines without backslash character

    • #7549: autosummary: Enable autosummary_generate by default

    • #8898: extlinks: Allow %s in link caption string

    • #4826: py domain: Add :canonical: option to python directives to describe the location where the object is defined

    • #7199: py domain: Add python_use_unqualified_type_names to suppress the module name of the python reference if it can be resolved (experimental)

    • #7068: py domain: Add py:property directive to describe a property

    • #7784: i18n: The alt text for image is translated by default (without gettext_additional_targets setting)

    • #2018: html: html_favicon and html_logo now accept URL for the image

    • #8070: html search: Support searching for 2characters word

    • #9036: html theme: Allow to inherite the search page

    • #8938: imgconverter: Show the error of the command availability check

    • #7830: Add debug logs for change detection of sources and templates

    • #8201: Emit a warning if toctree contains duplicated entries

    • #8326: master_doc is now renamed to root_doc

    • #8942: C++, add support for the C++20 spaceship operator, <=>.

    • #7199: A new node, sphinx.addnodes.pending_xref_condition has been added. It can be used to choose appropriate content of the reference by conditions.


    • #8818: autodoc: Super class having Any arguments causes nit-picky warning

    • #9095: autodoc: TypeError is raised on processing broken metaclass

    • #9110: autodoc: metadata of GenericAlias is not rendered as a reference in py37+

    • #9098: html: copy-range protection for doctests doesn’t work in Safari

    • #9103: LaTeX: imgconverter: conversion runs even if not needed

    • #8127: py domain: Ellipsis in info-field-list causes nit-picky warning

    • #9121: py domain: duplicated warning is emitted when both canonical and its alias objects are defined on the document

    • #9023: More CSS classes on domain descriptions, see Doctree node classes added by Sphinx for details.

    • #8195: mathjax: Rename mathjax_config to mathjax2_config and add mathjax3_config

    Bugs fixed


    • #8917: autodoc: Raises a warning if function has wrong __globals__ value

    • #8415: autodoc: a TypeVar imported from other module is not resolved (in Python 3.7 or above)

    • #8992: autodoc: Failed to resolve types.TracebackType type annotation

    • #8905: html: html_add_permalinks=None and html_add_permalinks=”” are ignored

    • #8380: html search: Paragraphs in search results are not identified as

    • #8915: html theme: The translation of sphinx_rtd_theme does not work

    • #8342: Emit a warning if a unknown domain is given for directive or role (ex. :unknown:doc:)

    • #7241: LaTeX: No wrapping for cpp:enumerator

    • #8711: LaTeX: backticks in code-blocks trigger latexpdf build warning (and font change) with late TeXLive 2019

    • #8253: LaTeX: Figures with no size defined get overscaled (compared to images with size explicitly set in pixels) (fixed for 'pdflatex'/'lualatex' only)

    • #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for navigation

    • #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output issues ignore Pygments style

    • #8925: LaTeX: 3.5.0 verbatimmaxunderfull setting does not work as expected

    • #8980: LaTeX: missing line break in \pysigline

    • #8995: LaTeX: legacy \pysiglinewithargsret does not compute correctly available horizontal space and should use a ragged right style

    • #9009: LaTeX: “release” value with underscore leads to invalid LaTeX

    • #8911: C++: remove the longest matching prefix in cpp_index_common_prefix instead of the first that matches.

    • C, properly reject function declarations when a keyword is used as parameter name.

    • #8933: viewcode: Failed to create back-links on parallel build

    • #8960: C and C++, fix rendering of (member) function pointer types in function parameter lists.

    • C++, fix linking of names in array declarators, pointer to member (function) declarators, and in the argument to sizeof....

    • C, fix linking of names in array declarators.


    • C, C++, fix KeyError when an alias directive is the first C/C++ directive in a file with another C/C++ directive later.


    • #9167: html: Failed to add CSS files to the specific page

    Release 3.5.5 (in development)

    Release 3.5.4 (released Apr 11, 2021)


    • #9071: Restrict docutils to 0.16

    Bugs fixed

    • #9078: autodoc: Async staticmethods and classmethods are considered as non async coroutine-functions with Python3.10

    • #8870, #9001, #9051: html theme: The style are not applied with docutils-0.17

      • toctree captions

      • The content of sidebar directive

      • figures

    Release 3.5.3 (released Mar 20, 2021)

    Features added

    • #8959: using UNIX path separator in image directive confuses Sphinx on Windows

    Release 3.5.2 (released Mar 06, 2021)

    Bugs fixed

    • #8943: i18n: Crashed by broken translation messages in ES, EL and HR

    • #8936: LaTeX: A custom LaTeX builder fails with unknown node error

    • #8952: Exceptions raised in a Directive cause parallel builds to hang

    Release 3.5.1 (released Feb 16, 2021)

    Bugs fixed

    • #8883: autodoc: AttributeError is raised on assigning __annotations__ on read-only class

    • #8884: html: minified js stemmers not included in the distributed package

    • #8885: html: AttributeError is raised if CSS/JS files are installed via html_context

    • #8880: viewcode: ExtensionError is raised on incremental build after unparsable python module found

    Release 3.5.0 (released Feb 14, 2021)


    • LaTeX: multicol (it is anyhow a required part of the official latex2e base distribution)

    Incompatible changes


    • pending_xref node for viewcode extension











    • sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()

    • sphinx.ext.autodoc.directive.DocumenterBridge.reporter

    • sphinx.ext.autodoc.importer.get_module_members()

    • sphinx.ext.autosummary.generate._simple_info()

    • sphinx.ext.autosummary.generate._simple_warn()

    • sphinx.writers.html.HTMLTranslator.permalink_text

    • sphinx.writers.html5.HTML5Translator.permalink_text

    Features added

    • #8022: autodoc: autodata and autoattribute directives does not show right-hand value of the variable if docstring contains :meta hide-value: in info-field-list

    • #8514: autodoc: Default values of overloaded functions are taken from actual implementation if they’re ellipsis

    • #8775: autodoc: Support type union operator (PEP-604) in Python 3.10 or above

    • #8297: autodoc: Allow to extend autodoc_default_options via directive options

    • #759: autodoc: Add a new configuration autodoc_preserve_defaults as an experimental feature. It preserves the default argument values of functions in source code and keep them not evaluated for readability.

    • #8619: html: kbd role generates customizable HTML tags for compound keys

    • #8634: html: Allow to change the order of JS/CSS via priority parameter for Sphinx.add_js_file() and Sphinx.add_css_file()

    • #6241: html: Allow to add JS/CSS files to the specific page when an extension calls app.add_js_file() or app.add_css_file() on html-page-context event

    • #6550: html: Allow to use HTML permalink texts via html_permalinks_icon

    • #1638: html: Add permalink icons to glossary terms

    • #8868: html search: performance issue with massive lists

    • #8867: html search: Update JavaScript stemmer code to the latest version of Snowball (v2.1.0)

    • #8852: i18n: Allow to translate heading syntax in MyST-Parser

    • #8649: imgconverter: Skip availability check if builder supports the image type

    • #8573: napoleon: Allow to change the style of custom sections using napoleon_custom_styles

    • #8004: napoleon: Type definitions in Google style docstrings are rendered as references when napoleon_preprocess_types enabled

    • #6241: mathjax: Include mathjax.js only on the document using equations

    • #8775: py domain: Support type union operator (PEP-604)

    • #8651: std domain: cross-reference for a rubric having inline item is broken

    • #7642: std domain: Optimize case-insensitive match of term

    • #8681: viewcode: Support incremental build

    • #8132: Add project_copyright as an alias of copyright

    • #207: Now highlight_language supports multiple languages

    • #2030: code-block and literalinclude supports automatic dedent via no-argument :dedent: option

    • C++, also hyperlink operator overloads in expressions and alias declarations.

    • #8247: Allow production lists to refer to tokens from other production groups

    • #8813: Show what extension (or module) caused it on errors on event handler

    • #8213: C++: add maxdepth option to cpp:alias to insert nested declarations.

    • C, add noroot option to c:alias to render only nested declarations.

    • C++, add noroot option to cpp:alias to render only nested declarations.

    Bugs fixed

    • #8727: apidoc: namespace module file is not generated if no submodules there

    • #741: autodoc: inherited-members doesn’t work for instance attributes on super class

    • #8592: autodoc: :meta public: does not effect to variables

    • #8594: autodoc: empty __all__ attribute is ignored

    • #8315: autodoc: Failed to resolve struct.Struct type annotation

    • #8652: autodoc: All variable comments in the module are ignored if the module contains invalid type comments

    • #8693: autodoc: Default values for overloaded functions are rendered as string

    • #8134: autodoc: crashes when mocked decorator takes arguments

    • #8800: autodoc: Uninitialized attributes in superclass are recognized as undocumented

    • #8655: autodoc: Failed to generate document if target module contains an object that raises an exception on hasattr()

    • #8306: autosummary: mocked modules are documented as empty page when using :recursive: option

    • #8232: graphviz: Image node is not rendered if graph file is in subdirectory

    • #8618: html: kbd role produces incorrect HTML when compound-key separators (-, + or ^) are used as keystrokes

    • #8629: html: A type warning for html_use_opensearch is shown twice

    • #8714: html: kbd role with “Caps Lock” rendered incorrectly

    • #8123: html search: fix searching for terms containing + (Requires a custom search language that does not split on +)

    • #8665: html theme: Could not override globaltoc_maxdepth in theme.conf

    • #8446: html: consecutive spaces are displayed as single space

    • #8745: i18n: crashes with KeyError when translation message adds a new auto footnote reference

    • #4304: linkcheck: Fix race condition that could lead to checking the availability of the same URL twice

    • #8791: linkcheck: The docname for each hyperlink is not displayed

    • #7118: sphinx-quickstart: questionare got Mojibake if libreadline unavailable

    • #8094: texinfo: image files on the different directory with document are not copied

    • #8782: todo: Cross references in todolist get broken

    • #8720: viewcode: module pages are generated for epub on incremental build

    • #8704: viewcode: anchors are generated in incremental build after singlehtml

    • #8756: viewcode: highlighted code is generated even if not referenced

    • #8671: highlight_options is not working

    • #8341: C, fix intersphinx lookup types for names in declarations.

    • C, C++: in general fix intersphinx and role lookup types.

    • #8683: html_last_updated_fmt does not support UTC offset (%z)

    • #8683: html_last_updated_fmt generates wrong time zone for %Z

    • #1112: download role creates duplicated copies when relative path is specified

    • #2616 (fifth item): LaTeX: footnotes from captions are not clickable, and for manually numbered footnotes only first one with same number is an hyperlink

    • #7576: LaTeX with French babel and memoir crash: “Illegal parameter number in definition of \[email protected]

    • #8055: LaTeX (docs): A potential display bug with the LaTeX generation step in Sphinx (how to generate one-column index)

    • #8072: LaTeX: Directive hlist not implemented in LaTeX

    • #8214: LaTeX: The index role and the glossary generate duplicate entries in the LaTeX index (if both used for same term)

    • #8735: LaTeX: wrong internal links in pdf to captioned code-blocks when numfig is not True

    • #8442: LaTeX: some indexed terms are ignored when using xelatex engine (or pdflatex and latex_use_xindy set to True) with memoir class

    • #8750: LaTeX: URLs as footnotes fail to show in PDF if originating from inside function type signatures

    • #8780: LaTeX: long words in narrow columns may not be hyphenated

    • #8788: LaTeX: \titleformat last argument in sphinx.sty should be bracketed, not braced (and is anyhow not needed)

    • #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX syntax boolean verbatimforcewraps for use via the ‘sphinxsetup’ key of latex_elements)

    • #8183: LaTeX: Remove substitution_reference nodes from doctree only on LaTeX builds

    • #8865: LaTeX: Restructure the index nodes inside title nodes only on LaTeX builds

    • #8796: LaTeX: potentially critical low level TeX coding mistake has gone unnoticed so far

    • C, c:alias skip symbols without explicit declarations instead of crashing.

    • C, c:alias give a warning when the root symbol is not declared.

    • C, expr role should start symbol lookup in the current scope.

    Release 3.4.3 (released Jan 08, 2021)

    Bugs fixed

    • #8655: autodoc: Failed to generate document if target module contains an object that raises an exception on hasattr()

    Release 3.4.2 (released Jan 04, 2021)

    Bugs fixed

    • #8164: autodoc: Classes that inherit mocked class are not documented

    • #8602: autodoc: The autodoc-process-docstring event is emitted to the non-datadescriptors unexpectedly

    • #8616: autodoc: AttributeError is raised on non-class object is passed to autoclass directive

    Release 3.4.1 (released Dec 25, 2020)

    Bugs fixed

    • #8559: autodoc: AttributeError is raised when using forward-reference type annotations

    • #8568: autodoc: TypeError is raised on checking slots attribute

    • #8567: autodoc: Instance attributes are incorrectly added to Parent class

    • #8566: autodoc: The autodoc-process-docstring event is emitted to the alias classes unexpectedly

    • #8583: autodoc: Unnecessary object comparison via __eq__ method

    • #8565: linkcheck: Fix PriorityQueue crash when link tuples are not comparable

    Release 3.4.0 (released Dec 20, 2020)

    Incompatible changes

    • #8105: autodoc: the signature of class constructor will be shown for decorated classes, not a signature of decorator


    • The follow_wrapped argument of sphinx.util.inspect.signature()

    • The no_docstring argument of sphinx.ext.autodoc.Documenter.add_content()

    • sphinx.ext.autodoc.Documenter.get_object_members()

    • sphinx.ext.autodoc.DataDeclarationDocumenter

    • sphinx.ext.autodoc.GenericAliasDocumenter

    • sphinx.ext.autodoc.InstanceAttributeDocumenter

    • sphinx.ext.autodoc.SlotsAttributeDocumenter

    • sphinx.ext.autodoc.TypeVarDocumenter

    • sphinx.ext.autodoc.importer._getannotations()

    • sphinx.ext.autodoc.importer._getmro()

    • sphinx.pycode.ModuleAnalyzer.parse()

    • sphinx.util.osutil.movefile()

    • sphinx.util.requests.is_ssl_error()

    Features added

    • #8119: autodoc: Allow to determine whether a member not included in __all__ attribute of the module should be documented or not via autodoc-skip-member event

    • #8219: autodoc: Parameters for generic class are not shown when super class is a generic class and show-inheritance option is given (in Python 3.7 or above)

    • autodoc: Add Documenter.config as a shortcut to access the config object

    • autodoc: Add Optional[t] to annotation of function and method if a default value equal to None is set.

    • #8209: autodoc: Add :no-value: option to autoattribute and autodata directive to suppress the default value of the variable

    • #8460: autodoc: Support custom types defined by typing.NewType

    • #8285: napoleon: Add napoleon_attr_annotations to merge type hints on source code automatically if any type is specified in docstring

    • #8236: napoleon: Support numpydoc’s “Receives” section

    • #6914: Add a new event warn-missing-reference to custom warning messages when failed to resolve a cross-reference

    • #6914: Emit a detailed warning when failed to resolve a :ref: reference

    • #6629: linkcheck: The builder now handles rate limits. See linkcheck_retry_on_rate_limit for details.

    Bugs fixed

    • #7613: autodoc: autodoc does not respect __signature__ of the class

    • #4606: autodoc: the location of the warning is incorrect for inherited method

    • #8105: autodoc: the signature of class constructor is incorrect if the class is decorated

    • #8434: autodoc: autodoc_type_aliases does not effect to variables and attributes

    • #8443: autodoc: autodata directive can’t create document for PEP-526 based type annotated variables

    • #8443: autodoc: autoattribute directive can’t create document for PEP-526 based uninitialized variables

    • #8480: autodoc: autoattribute could not create document for __slots__ attributes

    • #8503: autodoc: autoattribute could not create document for a GenericAlias as class attributes correctly

    • #8534: autodoc: autoattribute could not create document for a commented attribute in alias class

    • #8452: autodoc: autodoc_type_aliases doesn’t work when autodoc_typehints is set to “description”

    • #8541: autodoc: autodoc_type_aliases doesn’t work for the type annotation to instance attributes

    • #8460: autodoc: autodata and autoattribute directives do not display type information of TypeVars

    • #8493: autodoc: references to builtins not working in class aliases

    • #8522: autodoc: __bool__ method could be called

    • #8067: autodoc: A typehint for the instance variable having type_comment on super class is not displayed

    • #8545: autodoc: a __slots__ attribute is not documented even having docstring

    • #741: autodoc: inherited-members doesn’t work for instance attributes on super class

    • #8477: autosummary: non utf-8 reST files are generated when template contains multibyte characters

    • #8501: autosummary: summary extraction splits text after “el at.” unexpectedly

    • #8524: html: Wrong url_root has been generated on a document named “index”

    • #8419: html search: Do not load language_data.js in non-search pages

    • #8549: i18n: -D gettext_compact=0 is no longer working

    • #8454: graphviz: The layout option for graph and digraph directives don’t work

    • #8131: linkcheck: Use GET when HEAD requests cause Too Many Redirects, to accommodate infinite redirect loops on HEAD

    • #8437: Makefile: make clean with empty BUILDDIR is dangerous

    • #8365: py domain: :type: and :rtype: gives false ambiguous class lookup warnings

    • #8352: std domain: Failed to parse an option that starts with bracket

    • #8519: LaTeX: Prevent page brake in the middle of a seealso

    • #8520: C, fix copying of AliasNode.

    Release 3.3.1 (released Nov 12, 2020)

    Bugs fixed

    • #8372: autodoc: autoclass directive became slower than Sphinx-3.2

    • #7727: autosummary: raise PycodeError when documenting python package without

    • #8350: autosummary: autosummary_mock_imports causes slow down builds

    • #8364: C, properly initialize attributes in empty symbols.

    • #8399: i18n: Put system locale path after the paths specified by configuration

    Release 3.3.0 (released Nov 02, 2020)




    • sphinx.ext.autodoc.SingledispatchFunctionDocumenter

    • sphinx.ext.autodoc.SingledispatchMethodDocumenter

    Features added

    • #8100: html: Show a better error message for failures on copying html_static_files

    • #8141: C: added a maxdepth option to c:alias to insert nested declarations.

    • #8081: LaTeX: Allow to add LaTeX package via app.add_latex_package() until just before writing .tex file

    • #7996: manpage: Add man_make_section_directory to make a section directory on build man page

    • #8289: epub: Allow to suppress “duplicated ToC entry found” warnings from epub builder using suppress_warnings.

    • #8298: sphinx-quickstart: Add sphinx-quickstart --no-sep option

    • #8304: sphinx.testing: Register public markers in sphinx.testing.fixtures

    • #8051: napoleon: use the obj role for all See Also items

    • #8050: napoleon: Apply napoleon_preprocess_types to every field

    • C and C++, show line numbers for previous declarations when duplicates are detected.

    • #8183: Remove substitution_reference nodes from doctree only on LaTeX builds

    Bugs fixed

    • #8085: i18n: Add support for having single text domain

    • #6640: i18n: Failed to override system message translation

    • #8143: autodoc: AttributeError is raised when False value is passed to autodoc_default_options

    • #8103: autodoc: functools.cached_property is not considered as a property

    • #8190: autodoc: parsing error is raised if some extension replaces docstring by string not ending with blank lines

    • #8142: autodoc: Wrong constructor signature for the class derived from typing.Generic

    • #8157: autodoc: TypeError is raised when annotation has invalid __args__

    • #7964: autodoc: Tuple in default value is wrongly rendered

    • #8200: autodoc: type aliases break type formatting of autoattribute

    • #7786: autodoc: can’t detect overloaded methods defined in other file

    • #8294: autodoc: single-string __slots__ is not handled correctly

    • #7785: autodoc: autodoc_typehints=’none’ does not effect to overloaded functions

    • #8192: napoleon: description is disappeared when it contains inline literals

    • #8142: napoleon: Potential of regex denial of service in google style docs

    • #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex

    • #8215: LaTeX: ‘oneside’ classoption causes build warning

    • #8175: intersphinx: Potential of regex denial of service by broken inventory

    • #8277: sphinx-build: missing and redundant spacing (and etc) for console output on building

    • #7973: imgconverter: Check availability of imagemagick many times

    • #8255: py domain: number in default argument value is changed from hexadecimal to decimal

    • #8316: html: Prevent arrow keys changing page when button elements are focused

    • #8343: html search: Fix unnecessary load of images when parsing the document

    • #8254: html theme: Line numbers misalign with code lines

    • #8093: The highlight warning has wrong location in some builders (LaTeX, singlehtml and so on)

    • #8215: Eliminate Fancyhdr build warnings for oneside documents

    • #8239: Failed to refer a token in productionlist if it is indented

    • #8268: linkcheck: Report HTTP errors when linkcheck_anchors is True

    • #8245: linkcheck: take source directory into account for local files

    • #8321: linkcheck: tel: schema hyperlinks are detected as errors

    • #8323: linkcheck: An exit status is incorrect when links having unsupported schema found

    • #8188: C, add missing items to internal object types dictionary, e.g., preventing intersphinx from resolving them.

    • C, fix anon objects in intersphinx.

    • #8270, C++, properly reject functions as duplicate declarations if a non-function declaration of the same name already exists.

    • C, fix references to function parameters. Link to the function instead of a non-existing anchor.

    • #6914: figure numbers are unexpectedly assigned to uncaptioned items

    • #8320: make “inline” line numbers un-selectable


    • #8257: Support parallel build in sphinx.testing

    Release 3.2.1 (released Aug 14, 2020)

    Features added

    • #8095: napoleon: Add napoleon_preprocess_types to enable the type preprocessor for numpy style docstrings

    • #8114: C and C++, parse function attributes after parameters and qualifiers.

    Bugs fixed

    • #8074: napoleon: Crashes during processing C-ext module

    • #8088: napoleon: “Inline literal start-string without end-string” warning in Numpy style Parameters section

    • #8084: autodoc: KeyError is raised on documenting an attribute of the broken class

    • #8091: autodoc: AttributeError is raised on documenting an attribute on Python 3.5.2

    • #8099: autodoc: NameError is raised when target code uses TYPE_CHECKING

    • C++, fix parsing of template template parameters, broken by the fix of #7944

    Release 3.2.0 (released Aug 08, 2020)


    • sphinx.ext.autodoc.members_set_option()

    • sphinx.ext.autodoc.merge_special_members_option()

    • sphinx.writers.texinfo.TexinfoWriter.desc

    • C, parsing of pre-v3 style type directives and roles, along with the options c_allow_pre_v3 and c_warn_on_allowed_pre_v3.

    Features added

    • #2076: autodoc: Allow overriding of exclude-members in skip-member function

    • #8034: autodoc: :private-member: can take an explicit list of member names to be documented

    • #2024: autosummary: Add autosummary_filename_map to avoid conflict of filenames between two object with different case

    • #8011: autosummary: Support instance attributes as a target of autosummary directive

    • #7849: html: Add html_codeblock_linenos_style to change the style of line numbers for code-blocks

    • #7853: C and C++, support parameterized GNU style attributes.

    • #7888: napoleon: Add aliases Warn and Raise.

    • #7690: napoleon: parse type strings and make them hyperlinks as possible. The conversion rule can be updated via napoleon_type_aliases

    • #8049: napoleon: Create a hyperlink for each the type of parameter when napoleon_use_params is False

    • C, added c:alias directive for inserting copies of existing declarations.

    • #7745: html: inventory is broken if the docname contains a space

    • #7991: html search: Allow searching for numbers

    • #7902: html theme: Add a new option globaltoc_maxdepth to control the behavior of globaltoc in sidebar

    • #7840: i18n: Optimize the dependencies check on bootstrap

    • #7768: i18n: figure_language_filename supports docpath token

    • #5208: linkcheck: Support checks for local links

    • #5090: setuptools: Link verbosity to distutils’ -v and -q option

    • #6698: doctest: Add :trim-doctest-flags: and :no-trim-doctest-flags: options to doctest, testcode and testoutput directives

    • #7052: add :noindexentry: to the Python, C, C++, and Javascript domains. Update the documentation to better reflect the relationship between this option and the :noindex: option.

    • #7899: C, add possibility of parsing of some pre-v3 style type directives and roles and try to convert them to equivalent v3 directives/roles. Set the new option c_allow_pre_v3 to True to enable this. The warnings printed from this functionality can be suppressed by setting c_warn_on_allowed_pre_v3` to True. The functionality is immediately deprecated.

    • #7999: C, add support for named variadic macro arguments.

    • #8071: Allow to suppress “self referenced toctrees” warning

    Bugs fixed

    • #7886: autodoc: TypeError is raised on mocking generic-typed classes

    • #7935: autodoc: function signature is not shown when the function has a parameter having inspect._empty as its default value

    • #7901: autodoc: type annotations for overloaded functions are not resolved

    • #904: autodoc: An instance attribute cause a crash of autofunction directive

    • #1362: autodoc: private-members option does not work for class attributes

    • #7983: autodoc: Generator type annotation is wrongly rendered in py36

    • #8030: autodoc: An uninitialized annotated instance variable is not documented when :inherited-members: option given

    • #8032: autodoc: A type hint for the instance variable defined at parent class is not shown in the document of the derived class

    • #8041: autodoc: An annotated instance variable on super class is not documented when derived class has other annotated instance variables

    • #7839: autosummary: cannot handle umlauts in function names

    • #7865: autosummary: Failed to extract summary line when abbreviations found

    • #7866: autosummary: Failed to extract correct summary line when docstring contains a hyperlink target

    • #7469: autosummary: “Module attributes” header is not translatable

    • #7940: apidoc: An extra newline is generated at the end of the rst file if a module has submodules

    • #4258: napoleon: decorated special methods are not shown

    • #7799: napoleon: parameters are not escaped for combined params in numpydoc

    • #7780: napoleon: multiple paramaters declaration in numpydoc was wrongly recognized when napoleon_use_params=True

    • #7715: LaTeX: numfig_secnum_depth > 1 leads to wrong figure links

    • #7846: html theme: XML-invalid files were generated

    • #7894: gettext: Wrong source info is shown when using rst_epilog

    • #7691: linkcheck: HEAD requests are not used for checking

    • #4888: i18n: Failed to add an explicit title to :ref: role on translation

    • #7928: py domain: failed to resolve a type annotation for the attribute

    • #8008: py domain: failed to parse a type annotation containing ellipsis

    • #7994: std domain: option directive does not generate old node_id compatible with 2.x or older

    • #7968: i18n: The content of math directive is interpreted as reST on translation

    • #7768: i18n: The root element for figure_language_filename is not a path that user specifies in the document

    • #7993: texinfo: TypeError is raised for nested object descriptions

    • #7993: texinfo: a warning not supporting desc_signature_line node is shown

    • #7869: abbr role without an explanation will show the explanation from the previous abbr role

    • #8048: graphviz: graphviz.css was copied on building non-HTML document

    • C and C++, removed noindex directive option as it did nothing.

    • #7619: Duplicated node IDs are generated if node has multiple IDs

    • #2050: Symbols sections are appeared twice in the index page

    • #8017: Fix circular import in sphinx.addnodes

    • #7986: CSS: make “highlight” selector more robust

    • #7944: C++, parse non-type template parameters starting with a dependent qualified name.

    • C, don’t deepcopy the entire symbol table and make a mess every time an enumerator is handled.

    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)


    • #7746: mathjax: Update to 2.7.5

    Incompatible changes

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


    • 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 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.

    Release 3.0.4 (released May 27, 2020)

    Bugs fixed

    • #7567: autodoc: parametrized types are shown twice for generic types

    • #7637: autodoc: system defined TypeVars are shown in Python 3.9

    • #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security reasons

    • #7611: md5 fails when OpenSSL FIPS is enabled

    • #7626: release package does not contain CODE_OF_CONDUCT

    Release 3.0.3 (released Apr 26, 2020)

    Features added

    • C, parse array declarators with static, qualifiers, and VLA specification.

    Bugs fixed

    • #7516: autodoc: crashes if target object raises an error on accessing its attributes

    Release 3.0.2 (released Apr 19, 2020)

    Features added

    Bugs fixed

    • #7461: py domain: fails with IndexError for empty tuple in type annotation

    • #7510: py domain: keyword-only arguments are documented as having a default of None

    • #7418: std domain: term role could not match case-insensitively

    • #7461: autodoc: empty tuple in type annotation is not shown correctly

    • #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking

    • C++, fix spacing issue in east-const declarations.

    • #7414: LaTeX: Xindy language options were incorrect

    • sphinx crashes with ImportError on python3.5.1

    Release 3.0.1 (released Apr 11, 2020)

    Incompatible changes

    • #7418: std domain: term role becomes case sensitive

    Bugs fixed

    • #7428: py domain: a reference to class None emits a nitpicky warning

    • #7445: py domain: a return annotation None in the function signature is not converted to a hyperlink when using intersphinx

    • #7418: std domain: duplication warning for glossary terms is case insensitive

    • #7438: C++, fix merging overloaded functions in parallel builds.

    • #7422: autodoc: fails with ValueError when using autodoc_mock_imports

    • #7435: autodoc: autodoc_typehints='description' doesn’t suppress typehints in signature for classes/methods

    • #7451: autodoc: fails with AttributeError when an object returns non-string object as a __doc__ member

    • #7423: crashed when giving a non-string object to logger

    • #7479: html theme: Do not include xmlns attribute with HTML 5 doctype

    • #7426: html theme: Escape some links in HTML templates

    Release 3.0.0 (released Apr 06, 2020)



    • LaTeX: drop dependency on extractbb for image inclusion in Japanese documents as .xbb files are unneeded by dvipdfmx since TeXLive2015 (refs: #6189)

    • babel-2.0 or above is available (Unpinned)

    Incompatible changes


    • Drop features and APIs deprecated in 1.8.x

    • #247: autosummary: stub files are overwritten automatically by default. see autosummary_generate_overwrite to change the behavior

    • #5923: autodoc: the members of object class are not documented by default when :inherited-members: and :special-members: are given.

    • #6830: py domain: meta fields in info-field-list becomes reserved. They are not displayed on output document now

    • #6417: py domain: doctree of desc_parameterlist has been changed. The argument names, annotations and default values are wrapped with inline node

    • The structure of has changed

    • Due to the scoping changes for productionlist some uses of token must be modified to include the scope which was previously ignored.

    • #6903: Internal data structure of Python, reST and standard domains have changed. The node_id is added to the index of objects and modules. Now they contains a pair of docname and node_id for cross reference.

    • #7276: C++ domain: Non intended behavior is removed such as say_hello_ links to .. cpp:function:: say_hello()

    • #7210: js domain: Non intended behavior is removed such as parseInt_ links to .. js:function:: parseInt

    • #7229: rst domain: Non intended behavior is removed such as numref_ links to .. rst:role:: numref

    • #6903: py domain: Non intended behavior is removed such as say_hello_ links to .. py:function:: say_hello()

    • #7246: py domain: Drop special cross reference helper for exceptions, functions and methods

    • The C domain has been rewritten, with additional directives and roles. The existing ones are now more strict, resulting in new warnings.

    • The attribute sphinx_cpp_tagname in the desc_signature_line node has been renamed to sphinx_line_type.

    • #6462: double backslashes in domain directives are no longer replaced by single backslashes as default. A new configuration value strip_signature_backslash can be used by users to reenable it.

    3.0.0 final

    • #7222: sphinx.util.inspect.unwrap() is renamed to unwrap_all()



    • desc_signature['first']

    • sphinx.directives.DescDirective



    • sphinx.ext.autodoc.get_documenters()

    • sphinx.ext.autosummary.process_autosummary_toc()


    • sphinx.testing.path.Path.text()

    • sphinx.testing.path.Path.bytes()

    • sphinx.util.inspect.getargspec()

    • sphinx.writers.latex.LaTeXWriter.format_docclass()

    Features added


    • #247: autosummary: Add autosummary_generate_overwrite to overwrite old stub file

    • #5923: autodoc: :inherited-members: option takes a name of anchestor class not to document inherited members of the class and uppers

    • #6830: autodoc: consider a member private if docstring contains :meta private: in info-field-list

    • #7165: autodoc: Support Annotated type (PEP-593)

    • #2815: autodoc: Support singledispatch functions and methods

    • #7079: autodoc: autodoc_typehints accepts "description" configuration. It shows typehints as object description

    • #7314: apidoc: Propagate --maxdepth option through package documents

    • #6558: glossary: emit a warning for duplicated glossary entry

    • #3106: domain: Register hyperlink target for index page automatically

    • #6558: std domain: emit a warning for duplicated generic objects

    • #6830: py domain: Add new event: object-description-transform

    • #6895: py domain: Do not emit nitpicky warnings for built-in types

    • py domain: Support lambda functions in function signature

    • #6417: py domain: Allow to make a style for arguments of functions and methods

    • #7238, #7239: py domain: Emit a warning on describing a python object if the entry is already added as the same name

    • #7341: py domain: type annotations in signature are converted to cross refs

    • Support priority of event handlers. For more detail, see Sphinx.connect()

    • #3077: Implement the scoping for productionlist as indicated in the documentation.

    • #1027: Support backslash line continuation in productionlist.

    • #7108: config: Allow to show an error message from via ConfigError

    • #7032: html: html_scaled_image_link will be disabled for images having no-scaled-link class

    • #7144: Add CSS class indicating its domain for each desc node

    • #7211: latex: Use babel for Chinese document when using XeLaTeX

    • #6672: LaTeX: Support LaTeX Theming (experimental)

    • #7005: LaTeX: Add LaTeX styling macro for kbd role

    • #7220: genindex: Show “main” index entries at first

    • #7103: linkcheck: writes all links to output.json

    • #7025: html search: full text search can be disabled for individual document using :nosearch: file-wide metadata

    • #7293: html search: Allow to override JavaScript splitter via SearchLanguage.js_splitter_code

    • #7142: html theme: Add a theme option: pygments_dark_style to switch the style of code-blocks in dark mode

    • The C domain has been rewritten adding for example:

      • Cross-referencing respecting the current scope.

      • Possible to document anonymous entities.

      • More specific directives and roles for each type of entitiy, e.g., handling scoping of enumerators.

      • New role c:expr for rendering expressions and types in text.

    • Added SphinxDirective.get_source_info() and SphinxRole.get_source_info().

    • #7324: sphinx-build: Emit a warning if multiple files having different file extensions for same document found

    3.0.0 final

    • Added ObjectDescription.transform_content().

    Bugs fixed


    • C++, fix cross reference lookup in certain cases involving function overloads.

    • #5078: C++, fix cross reference lookup when a directive contains multiple declarations.

    • C++, suppress warnings for directly dependent typenames in cross references generated automatically in signatures.

    • #5637: autodoc: Incorrect handling of nested class names on show-inheritance

    • #7267: autodoc: error message for invalid directive options has wrong location

    • #7329: autodoc: info-field-list is wrongly generated from type hints into the class description even if autoclass_content='class' set

    • #7331: autodoc: a cython-function is not recognized as a function

    • #5637: inheritance_diagram: Incorrect handling of nested class names

    • #7139: code-block:: guess does not work

    • #7325: html: source_suffix containing dot leads to wrong source link

    • #7357: html: Resizing SVG image fails with ValueError

    • #7278: html search: Fix use of html_file_suffix instead of html_link_suffix in search results

    • #7297: html theme: bizstyle does not support sidebarwidth

    • #3842: singlehtml: Path to images broken when master doc is not in source root

    • #7179: std domain: Fix whitespaces are suppressed on referring GenericObject

    • #7289: console: use bright colors instead of bold

    • #1539: C, parse array types.

    • #2377: C, parse function pointers even in complex types.

    • #7345: sphinx-build: Sphinx crashes if output directory exists as a file

    • #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions

    • #6240: napoleon: Attributes and Methods sections ignore :noindex: option

    3.0.0 final

    • #7364: autosummary: crashed when autosummary_generate is False

    • #7370: autosummary: raises UnboundLocalError when unknown module given

    • #7367: C++, alternate operator spellings are now supported.

    • C, alternate operator spellings are now supported.

    • #7368: C++, comma operator in expressions, pack expansion in template argument lists, and more comprehensive error messages in some cases.

    • C, C++, fix crash and wrong duplicate warnings related to anon symbols.

    • #6477: Escape first “!” in a cross reference linking no longer possible

    • #7219: py domain: The index entry generated by py:function directive is different with one from index directive with “builtin” type

    • #7301: capital characters are not allowed for node_id

    • #7301: epub: duplicated node_ids are generated

    • #6564: html: a width of table was ignored on HTML builder

    • #7401: Incorrect argument is passed for env-get-outdated handlers

    • #7355: autodoc: a signature of cython-function is not recognized well

    • #7222: autodoc: __wrapped__ functions are not documented correctly

    • #7409: intersphinx: ValueError is raised when an extension sets up intersphinx_mapping on config-inited event

    • #7343: Sphinx builds has been slower since 2.4.0 on debug mode

    Release 2.4.4 (released Mar 05, 2020)

    Bugs fixed

    • #7197: LaTeX: platex cause error to build image directive with target url

    • #7223: Sphinx builds has been slower since 2.4.0

    Release 2.4.3 (released Feb 22, 2020)

    Bugs fixed

    • #7184: autodoc: *args and **kwarg in type comments are not handled properly

    • #7189: autodoc: classmethod coroutines are not detected

    • #7183: intersphinx: :attr: reference to property is broken

    • #6244, #6387: html search: Search breaks/hangs when built with dirhtml builder

    • #7195: todo: emit doctree-resolved event with non-document node incorrectly

    Release 2.4.2 (released Feb 19, 2020)

    Bugs fixed

    • #7138: autodoc: autodoc.typehints crashed when variable has unbound object as a value

    • #7156: autodoc: separator for keyword only arguments is not shown

    • #7146: autodoc: IndexError is raised on suppressed type_comment found

    • #7161: autodoc: typehints extension does not support parallel build

    • #7178: autodoc: TypeError is raised on fetching type annotations

    • #7151: crashed when extension assigns a value to env.indexentries

    • #7170: text: Remove debug print

    • #7137: viewcode: Avoid to crash when non-python code given

    Release 2.4.1 (released Feb 11, 2020)

    Bugs fixed

    • #7120: html: crashed when on scaling SVG images which have float dimensions

    • #7126: autodoc: TypeError: ‘getset_descriptor’ object is not iterable

    Release 2.4.0 (released Feb 09, 2020)


    • The decode argument of sphinx.pycode.ModuleAnalyzer()

    • sphinx.directives.other.Index

    • sphinx.environment.temp_data['gloss_entries']

    • sphinx.environment.BuildEnvironment.indexentries

    • sphinx.environment.collectors.indexentries.IndexEntriesCollector

    • sphinx.ext.apidoc.INITPY

    • sphinx.ext.apidoc.shall_skip()



    • sphinx.pycode.ModuleAnalyzer.encoding

    • sphinx.roles.Index

    • sphinx.util.detect_encoding()

    • sphinx.util.get_module_source()

    • sphinx.util.inspect.Signature

    • sphinx.util.inspect.safe_getmembers()


    • sphinx.writers.latex.LaTeXTranslator.settings.contentsname

    • sphinx.writers.latex.LaTeXTranslator.settings.docclass

    • sphinx.writers.latex.LaTeXTranslator.settings.docname

    • sphinx.writers.latex.LaTeXTranslator.settings.title

    • sphinx.writers.latex.ADDITIONAL_SETTINGS

    • sphinx.writers.latex.DEFAULT_SETTINGS

    • sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG

    • sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG

    • sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG

    • sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG

    Features added

    • #6910: inheritance_diagram: Make the background of diagrams transparent

    • #6446: duration: Add sphinx.ext.durations to inspect which documents slow down the build

    • #6837: LaTeX: Support a nested table

    • #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via environment variable

    • #6966: graphviz: Support :class: option

    • #6696: html: :scale: option of image/figure directive not working for SVG images (imagesize-1.2.0 or above is required)

    • #6994: imgconverter: Support illustrator file (.ai) to .png conversion

    • autodoc: Support Positional-Only Argument separator (PEP-570 compliant)

    • autodoc: Support type annotations for variables

    • #2755: autodoc: Add new event: autodoc-before-process-signature

    • #2755: autodoc: Support type_comment style (ex. # type: (str) -> str) annotation (python3.8+ or typed_ast is required)

    • #7051: autodoc: Support instance variables without defaults (PEP-526)

    • #6418: autodoc: Add a new extension sphinx.ext.autodoc.typehints. It shows typehints as object description if autodoc_typehints = "description" set. This is an experimental extension and it will be integrated into autodoc core in Sphinx-3.0

    • SphinxTranslator now calls visitor/departure method for super node class if visitor/departure method for original node class not found

    • #6418: Add new event: object-description-transform

    • py domain: py:data and py:attribute take new options named :type: and :value: to describe its type and initial value

    • #6785: py domain: :py:attr: is able to refer properties again

    • #6772: apidoc: Add -q option for quiet mode

    Bugs fixed

    • #6925: html: Remove redundant type=”text/javascript” from