Changelog

Release 4.2.0 (in development)

Dependencies

Incompatible changes

Deprecated

Features added

Bugs fixed

Testing

Release 4.1.2 (in development)

Dependencies

Incompatible changes

Deprecated

Features added

Bugs fixed

Testing

Release 4.1.1 (released Jul 15, 2021)

Dependencies

#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)

Dependencies

Support jinja2-3.0

Deprecated

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 foo.bar.BazClass
#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 github.com
#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 conf.py 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)

Dependencies

#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)

Dependencies

4.0.0b1

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

4.0.0b2

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

4.0.0b1

#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

4.0.0b2
- #9023: Change the CSS classes on cpp:expr and cpp:texpr.
Deprecated
- 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

4.0.0b1
- #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.
4.0.0b2
- #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

4.0.0b1
- #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.
4.0.0b2
- C, C++, fix KeyError when an alias directive is the first C/C++ directive in a file with another C/C++ directive later.
4.0.0b3
- #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)
Dependencies
- #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)
Dependencies
- LaTeX: multicol (it is anyhow a required part of the official latex2e base distribution)
Incompatible changes
- Update Underscore.js to 1.12.0
- #6550: html: The config variable html_add_permalinks is replaced by html_permalinks and html_permalinks_icon
Deprecated
- pending_xref node for viewcode extension
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.good
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers
- sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue
- sphinx.builders.linkcheck.node_line_or_0()
- 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 \FNH@prefntext”
- #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
Deprecated
- 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 __init__.py
- #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)
Deprecated
- sphinx.builders.latex.LaTeXBuilder.usepackages
- sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref
- 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
Testing
- #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)
Deprecated
- 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)
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 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
- C, parse attributes and add c_id_attributes and c_paren_attributes to support user-defined attributes.
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)
Dependencies

3.0.0b1
- 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

3.0.0b1
- 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 sphinx.events.EventManager.listeners 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()
Deprecated

3.0.0b1
- desc_signature['first']
- sphinx.directives.DescDirective
- sphinx.domains.std.StandardDomain.add_object()
- sphinx.domains.python.PyDecoratorMixin
- sphinx.ext.autodoc.get_documenters()
- sphinx.ext.autosummary.process_autosummary_toc()
- sphinx.parsers.Parser.app
- sphinx.testing.path.Path.text()
- sphinx.testing.path.Path.bytes()
- sphinx.util.inspect.getargspec()
- sphinx.writers.latex.LaTeXWriter.format_docclass()
Features added

3.0.0b1
- #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 conf.py 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

3.0.0b1
- 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)
Deprecated
- 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.io.FiletypeNotFoundError
- sphinx.io.get_filetype()
- 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.author
- 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

Changelog

Changelog

Release 4.2.0 (in development)

Dependencies

Incompatible changes

Deprecated

Features added

Bugs fixed

Testing

Release 4.1.2 (in development)

Dependencies

Incompatible changes

Deprecated

Features added

Bugs fixed

Testing

Release 4.1.1 (released Jul 15, 2021)

Dependencies

Bugs fixed

Release 4.1.0 (released Jul 12, 2021)

Dependencies

Deprecated

Features added

Bugs fixed

Release 4.0.3 (released Jul 05, 2021)

Features added

Bugs fixed

Release 4.0.2 (released May 20, 2021)

Dependencies

Incompatible changes

Bugs fixed

Release 4.0.1 (released May 11, 2021)

Bugs fixed

Release 4.0.0 (released May 09, 2021)

Dependencies

Incompatible changes

Deprecated

Features added

Bugs fixed

Release 3.5.5 (in development)

Release 3.5.4 (released Apr 11, 2021)

Dependencies

Bugs fixed

Release 3.5.3 (released Mar 20, 2021)

Features added

Release 3.5.2 (released Mar 06, 2021)

Bugs fixed

Release 3.5.1 (released Feb 16, 2021)

Bugs fixed

Release 3.5.0 (released Feb 14, 2021)

Dependencies

Incompatible changes

Deprecated

Features added

Bugs fixed

Release 3.4.3 (released Jan 08, 2021)

Bugs fixed

Release 3.4.2 (released Jan 04, 2021)

Bugs fixed

Release 3.4.1 (released Dec 25, 2020)

Bugs fixed

Release 3.4.0 (released Dec 20, 2020)

Incompatible changes

Deprecated

Features added

Bugs fixed

Release 3.3.1 (released Nov 12, 2020)

Bugs fixed

Release 3.3.0 (released Nov 02, 2020)

Deprecated

Features added

Bugs fixed

Testing

Release 3.2.1 (released Aug 14, 2020)

Features added

Bugs fixed

Release 3.2.0 (released Aug 08, 2020)

Deprecated

Features added

Bugs fixed