Changelog
### 4.4.0
```
=====================================
Dependencies
------------
* 10007: Use ``importlib_metadata`` for python-3.9 or older
* 10007: Drop ``setuptools``
Features added
--------------
* 9075: autodoc: Add a config variable :confval:`autodoc_typehints_format`
to suppress the leading module names of typehints of function signatures (ex.
``io.StringIO`` -> ``StringIO``)
* 9831: Autosummary now documents only the members specified in a module's
``__all__`` attribute if :confval:`autosummary_ignore_module_all` is set to
``False``. The default behaviour is unchanged. Autogen also now supports
this behavior with the ``--respect-module-all`` switch.
* 9555: autosummary: Improve error messages on failure to load target object
* 9800: extlinks: Emit warning if a hardcoded link is replaceable
by an extlink, suggesting a replacement.
* 9961: html: Support nested <kbd> HTML elements in other HTML builders
* 10013: html: Allow to change the loading method of JS via ``loading_method``
parameter for :meth:`Sphinx.add_js_file()`
* 9551: html search: "Hide Search Matches" link removes "highlight" parameter
from URL
* 9815: html theme: Wrap sidebar components in div to allow customizing their
layout via CSS
* 9827: i18n: Sort items in glossary by translated terms
* 9899: py domain: Allows to specify cross-reference specifier (``.`` and
``~``) as ``:type:`` option
* 9894: linkcheck: add option ``linkcheck_exclude_documents`` to disable link
checking in matched documents.
* 9793: sphinx-build: Allow to use the parallel build feature in macOS on macOS
and Python3.8+
* 10055: sphinx-build: Create directories when ``-w`` option given
* 9993: std domain: Allow to refer an inline target (ex. ``_`target name)
via :rst:role:`ref` role
* 9981: std domain: Strip value part of the option directive from general index
* 9391: texinfo: improve variable in ``samp`` role
* 9578: texinfo: Add :confval:`texinfo_cross_references` to disable cross
references for readability with standalone readers
* 9822 (and 9062), add new Intersphinx role :rst:role:`external` for explict
lookup in the external projects, without resolving to the local project.
Bugs fixed
----------
* 9866: autodoc: doccomment for the imported class was ignored
* 9883: autodoc: doccomment for the alias to mocked object was ignored
* 9908: autodoc: debug message is shown on building document using NewTypes
with Python 3.10
* 9968: autodoc: instance variables are not shown if __init__ method has
position-only-arguments
* 9194: autodoc: types under the "typing" module are not hyperlinked
* 10009: autodoc: Crashes if target object raises an error on getting docstring
* 10058: autosummary: Imported members are not shown when
``autodoc_class_signature = 'separated'``
* 9947: i18n: topic directive having a bullet list can't be translatable
* 9878: mathjax: MathJax configuration is placed after loading MathJax itself
* 9932: napoleon: empty "returns" section is generated even if no description
* 9857: Generated RFC links use outdated base url
* 9909: HTML, prevent line-wrapping in literal text.
* 10061: html theme: Configuration values added by themes are not be able to
override from conf.py
* 10073: imgconverter: Unnecessary availablity check is called for "data" URIs
* 9925: LaTeX: prohibit also with ``'xelatex'`` line splitting at dashes of
inline and parsed literals
* 9944: LaTeX: extra vertical whitespace for some nested declarations
* 9940: LaTeX: Multi-function declaration in Python domain has cramped
vertical spacing in latexpdf output
* 10015: py domain: types under the "typing" module are not hyperlinked defined
at info-field-list
* 9390: texinfo: Do not emit labels inside footnotes
* 9413: xml: Invalid XML was generated when cross referencing python objects
* 9979: Error level messages were displayed as warning messages
* 10057: Failed to scan documents if the project is placed onto the root
directory
* 9636: code-block: ``:dedent:`` without argument did strip newlines
```
### 4.3.2
```
=====================================
Bugs fixed
----------
* 9917: C and C++, parse fundamental types no matter the order of simple type
specifiers.
```
### 4.3.1
```
=====================================
Features added
--------------
* 9864: mathjax: Support chnaging the loading method of MathJax to "defer" via
:confval:`mathjax_options`
Bugs fixed
----------
* 9838: autodoc: AttributeError is raised on building document for functions
decorated by functools.lru_cache
* 9879: autodoc: AttributeError is raised on building document for an object
having invalid __doc__ attribute
* 9844: autodoc: Failed to process a function wrapped with functools.partial if
:confval:`autodoc_preserve_defaults` enabled
* 9872: html: Class namespace collision between autodoc signatures and
docutils-0.17
* 9868: imgmath: Crashed if the dvisvgm command failed to convert equation
* 9864: mathjax: Failed to render equations via MathJax v2. The loading method
of MathJax is back to "async" method again
```
### 4.3.0
```
=====================================
Dependencies
------------
* Support Python 3.10
Incompatible changes
--------------------
* 9649: ``searchindex.js``: the embedded data has changed format to allow
objects with the same name in different domains.
* 9672: The rendering of Python domain declarations is implemented
with more docutils nodes to allow better CSS styling.
It may break existing styling.
* 9672: the signature of
:py:meth:`domains.py.PyObject.get_signature_prefix` has changed to
return a list of nodes instead of a plain string.
* 9695: ``domains.js.JSObject.display_prefix`` has been changed into a method
``get_display_prefix`` which now returns a list of nodes
instead of a plain string.
* 9695: The rendering of Javascript domain declarations is implemented
with more docutils nodes to allow better CSS styling.
It may break existing styling.
* 9450: mathjax: Load MathJax via "defer" strategy
Deprecated
----------
* ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor``
* ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index``
* ``sphinx.writers.html.HTMLTranslator._table_row_index``
* ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index``
* ``sphinx.writers.html5.HTML5Translator._table_row_index``
Features added
--------------
* 9639: autodoc: Support asynchronous generator functions
* 9664: autodoc: ``autodoc-process-bases`` supports to inject reST snippet as a
base class
* 9691: C, added new info-field ``retval``
for :rst:dir:`c:function` and :rst:dir:`c:macro`.
* C++, added new info-field ``retval`` for :rst:dir:`cpp:function`.
* 9618: i18n: Add :confval:`gettext_allow_fuzzy_translations` to allow "fuzzy"
messages for translation
* 9672: More CSS classes on Python domain descriptions
* 9695: More CSS classes on Javascript domain descriptions
* 9683: Revert the removal of ``add_stylesheet()`` API. It will be kept until
the Sphinx-6.0 release
* 2068, add :confval:`intersphinx_disabled_reftypes` for disabling
interphinx resolution of cross-references that do not have an explicit
inventory specification. Specific types of cross-references can be disabled,
e.g., ``std:doc`` or all cross-references in a specific domain,
e.g., ``std:*``.
* 9623: Allow to suppress "toctree contains reference to excluded document"
warnings using :confval:`suppress_warnings`
Bugs fixed
----------
* 9630: autodoc: Failed to build cross references if :confval:`primary_domain`
is not 'py'
* 9644: autodoc: Crashed on getting source info from problematic object
* 9655: autodoc: mocked object having doc comment is warned unexpectedly
* 9651: autodoc: return type field is not generated even if
:confval:`autodoc_typehints_description_target` is set to "documented" when
its info-field-list contains ``:returns:`` field
* 9657: autodoc: The base class for a subclass of mocked object is incorrect
* 9607: autodoc: Incorrect base class detection for the subclasses of the
generic class
* 9755: autodoc: memory addresses are shown for aliases
* 9752: autodoc: Failed to detect type annotation for slots attribute
* 9756: autodoc: Crashed if classmethod does not have __func__ attribute
* 9757: autodoc: :confval:`autodoc_inherit_docstrings` does not effect to
overridden classmethods
* 9781: autodoc: :confval:`autodoc_preserve_defaults` does not support
hexadecimal numeric
* 9630: autosummary: Failed to build summary table if :confval:`primary_domain`
is not 'py'
* 9670: html: Fix download file with special characters
* 9710: html: Wrong styles for even/odd rows in nested tables
* 9763: html: parameter name and its type annotation are not separated in HTML
* 9649: HTML search: when objects have the same name but in different domains,
return all of them as result instead of just one.
* 7634: intersphinx: references on the file in sub directory are broken
* 9737: LaTeX: hlist is rendered as a list containing "aggedright" text
* 9678: linkcheck: file extension was shown twice in warnings
* 9697: py domain: An index entry with parens was registered for ``py:method``
directive with ``:property:`` option
* 9775: py domain: Literal typehint was converted to a cross reference when
:confval:`autodoc_typehints='description'`
* 9708: needs_extension failed to check double-digit version correctly
* 9688: Fix :rst:dir:`code`` does not recognize ``:class:`` option
* 9733: Fix for logging handler flushing warnings in the middle of the docs
build
* 9656: Fix warnings without subtype being incorrectly suppressed
* Intersphinx, for unresolved references with an explicit inventory,
e.g., ``proj:myFunc``, leave the inventory prefix in the unresolved text.
```
### 4.2.0
```
=====================================
Features added
--------------
* 9445: autodoc: Support class properties
* 9479: autodoc: Emit a warning if target is a mocked object
* 9560: autodoc: Allow to refer NewType instances with module name in Python
3.10 or above
* 9447: html theme: Expose the version of Sphinx in the form of tuple as a
template variable ``sphinx_version_tuple``
* 9594: manpage: Suppress the title of man page if description is empty
* 9445: py domain: ``:py:property:`` directive supports ``:classmethod:``
option to describe the class property
* 9524: test: SphinxTestApp can take ``builddir`` as an argument
* 9535: C and C++, support more fundamental types, including GNU extensions.
Bugs fixed
----------
* 9608: apidoc: apidoc does not generate a module definition for implicit
namespace package
* 9504: autodoc: generate incorrect reference to the parent class if the target
class inherites the class having ``_name`` attribute
* 9537, 9589: autodoc: Some objects under ``typing`` module are not displayed
well with the HEAD of 3.10
* 9487: autodoc: typehint for cached_property is not shown
* 9509: autodoc: AttributeError is raised on failed resolving typehints
* 9518: autodoc: autodoc_docstring_signature does not effect to ``__init__()``
and ``__new__()``
* 9522: autodoc: PEP 585 style typehints having arguments (ex. ``list[int]``)
are not displayed well
* 9481: autosummary: some warnings contain non-existing filenames
* 9568: autosummary: summarise overlined sectioned headings correctly
* 9600: autosummary: Type annotations which contain commas in autosummary table
are not removed completely
* 9481: c domain: some warnings contain non-existing filenames
* 9481: cpp domain: some warnings contain non-existing filenames
* 9456: html search: abbreation marks are inserted to the search result if
failed to fetch the content of the page
* 9617: html search: The JS requirement warning is shown if browser is slow
* 9267: html theme: CSS and JS files added by theme were loaded twice
* 9585: py domain: ``:type:`` option for :rst:dir:`py:property` directive does
not create a hyperlink
* 9576: py domain: Literal typehint was converted to a cross reference
* 9535 comment: C++, fix parsing of defaulted function parameters that are
function pointers.
* 9564: smartquotes: don't adjust typography for text with
language-highlighted ``:code:`` role.
* 9512: sphinx-build: crashed with the HEAD of Python 3.10
```
Links
- PyPI: https://pypi.org/project/sphinx
- Changelog: https://pyup.io/changelogs/sphinx/
- Homepage: https://www.sphinx-doc.org/
This PR updates Sphinx from 4.1.2 to 4.4.0.
Changelog
### 4.4.0 ``` ===================================== Dependencies ------------ * 10007: Use ``importlib_metadata`` for python-3.9 or older * 10007: Drop ``setuptools`` Features added -------------- * 9075: autodoc: Add a config variable :confval:`autodoc_typehints_format` to suppress the leading module names of typehints of function signatures (ex. ``io.StringIO`` -> ``StringIO``) * 9831: Autosummary now documents only the members specified in a module's ``__all__`` attribute if :confval:`autosummary_ignore_module_all` is set to ``False``. The default behaviour is unchanged. Autogen also now supports this behavior with the ``--respect-module-all`` switch. * 9555: autosummary: Improve error messages on failure to load target object * 9800: extlinks: Emit warning if a hardcoded link is replaceable by an extlink, suggesting a replacement. * 9961: html: Support nested <kbd> HTML elements in other HTML builders * 10013: html: Allow to change the loading method of JS via ``loading_method`` parameter for :meth:`Sphinx.add_js_file()` * 9551: html search: "Hide Search Matches" link removes "highlight" parameter from URL * 9815: html theme: Wrap sidebar components in div to allow customizing their layout via CSS * 9827: i18n: Sort items in glossary by translated terms * 9899: py domain: Allows to specify cross-reference specifier (``.`` and ``~``) as ``:type:`` option * 9894: linkcheck: add option ``linkcheck_exclude_documents`` to disable link checking in matched documents. * 9793: sphinx-build: Allow to use the parallel build feature in macOS on macOS and Python3.8+ * 10055: sphinx-build: Create directories when ``-w`` option given * 9993: std domain: Allow to refer an inline target (ex. ``_`target name) via :rst:role:`ref` role * 9981: std domain: Strip value part of the option directive from general index * 9391: texinfo: improve variable in ``samp`` role * 9578: texinfo: Add :confval:`texinfo_cross_references` to disable cross references for readability with standalone readers * 9822 (and 9062), add new Intersphinx role :rst:role:`external` for explict lookup in the external projects, without resolving to the local project. Bugs fixed ---------- * 9866: autodoc: doccomment for the imported class was ignored * 9883: autodoc: doccomment for the alias to mocked object was ignored * 9908: autodoc: debug message is shown on building document using NewTypes with Python 3.10 * 9968: autodoc: instance variables are not shown if __init__ method has position-only-arguments * 9194: autodoc: types under the "typing" module are not hyperlinked * 10009: autodoc: Crashes if target object raises an error on getting docstring * 10058: autosummary: Imported members are not shown when ``autodoc_class_signature = 'separated'`` * 9947: i18n: topic directive having a bullet list can't be translatable * 9878: mathjax: MathJax configuration is placed after loading MathJax itself * 9932: napoleon: empty "returns" section is generated even if no description * 9857: Generated RFC links use outdated base url * 9909: HTML, prevent line-wrapping in literal text. * 10061: html theme: Configuration values added by themes are not be able to override from conf.py * 10073: imgconverter: Unnecessary availablity check is called for "data" URIs * 9925: LaTeX: prohibit also with ``'xelatex'`` line splitting at dashes of inline and parsed literals * 9944: LaTeX: extra vertical whitespace for some nested declarations * 9940: LaTeX: Multi-function declaration in Python domain has cramped vertical spacing in latexpdf output * 10015: py domain: types under the "typing" module are not hyperlinked defined at info-field-list * 9390: texinfo: Do not emit labels inside footnotes * 9413: xml: Invalid XML was generated when cross referencing python objects * 9979: Error level messages were displayed as warning messages * 10057: Failed to scan documents if the project is placed onto the root directory * 9636: code-block: ``:dedent:`` without argument did strip newlines ``` ### 4.3.2 ``` ===================================== Bugs fixed ---------- * 9917: C and C++, parse fundamental types no matter the order of simple type specifiers. ``` ### 4.3.1 ``` ===================================== Features added -------------- * 9864: mathjax: Support chnaging the loading method of MathJax to "defer" via :confval:`mathjax_options` Bugs fixed ---------- * 9838: autodoc: AttributeError is raised on building document for functions decorated by functools.lru_cache * 9879: autodoc: AttributeError is raised on building document for an object having invalid __doc__ attribute * 9844: autodoc: Failed to process a function wrapped with functools.partial if :confval:`autodoc_preserve_defaults` enabled * 9872: html: Class namespace collision between autodoc signatures and docutils-0.17 * 9868: imgmath: Crashed if the dvisvgm command failed to convert equation * 9864: mathjax: Failed to render equations via MathJax v2. The loading method of MathJax is back to "async" method again ``` ### 4.3.0 ``` ===================================== Dependencies ------------ * Support Python 3.10 Incompatible changes -------------------- * 9649: ``searchindex.js``: the embedded data has changed format to allow objects with the same name in different domains. * 9672: The rendering of Python domain declarations is implemented with more docutils nodes to allow better CSS styling. It may break existing styling. * 9672: the signature of :py:meth:`domains.py.PyObject.get_signature_prefix` has changed to return a list of nodes instead of a plain string. * 9695: ``domains.js.JSObject.display_prefix`` has been changed into a method ``get_display_prefix`` which now returns a list of nodes instead of a plain string. * 9695: The rendering of Javascript domain declarations is implemented with more docutils nodes to allow better CSS styling. It may break existing styling. * 9450: mathjax: Load MathJax via "defer" strategy Deprecated ---------- * ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor`` * ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index`` * ``sphinx.writers.html.HTMLTranslator._table_row_index`` * ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index`` * ``sphinx.writers.html5.HTML5Translator._table_row_index`` Features added -------------- * 9639: autodoc: Support asynchronous generator functions * 9664: autodoc: ``autodoc-process-bases`` supports to inject reST snippet as a base class * 9691: C, added new info-field ``retval`` for :rst:dir:`c:function` and :rst:dir:`c:macro`. * C++, added new info-field ``retval`` for :rst:dir:`cpp:function`. * 9618: i18n: Add :confval:`gettext_allow_fuzzy_translations` to allow "fuzzy" messages for translation * 9672: More CSS classes on Python domain descriptions * 9695: More CSS classes on Javascript domain descriptions * 9683: Revert the removal of ``add_stylesheet()`` API. It will be kept until the Sphinx-6.0 release * 2068, add :confval:`intersphinx_disabled_reftypes` for disabling interphinx resolution of cross-references that do not have an explicit inventory specification. Specific types of cross-references can be disabled, e.g., ``std:doc`` or all cross-references in a specific domain, e.g., ``std:*``. * 9623: Allow to suppress "toctree contains reference to excluded document" warnings using :confval:`suppress_warnings` Bugs fixed ---------- * 9630: autodoc: Failed to build cross references if :confval:`primary_domain` is not 'py' * 9644: autodoc: Crashed on getting source info from problematic object * 9655: autodoc: mocked object having doc comment is warned unexpectedly * 9651: autodoc: return type field is not generated even if :confval:`autodoc_typehints_description_target` is set to "documented" when its info-field-list contains ``:returns:`` field * 9657: autodoc: The base class for a subclass of mocked object is incorrect * 9607: autodoc: Incorrect base class detection for the subclasses of the generic class * 9755: autodoc: memory addresses are shown for aliases * 9752: autodoc: Failed to detect type annotation for slots attribute * 9756: autodoc: Crashed if classmethod does not have __func__ attribute * 9757: autodoc: :confval:`autodoc_inherit_docstrings` does not effect to overridden classmethods * 9781: autodoc: :confval:`autodoc_preserve_defaults` does not support hexadecimal numeric * 9630: autosummary: Failed to build summary table if :confval:`primary_domain` is not 'py' * 9670: html: Fix download file with special characters * 9710: html: Wrong styles for even/odd rows in nested tables * 9763: html: parameter name and its type annotation are not separated in HTML * 9649: HTML search: when objects have the same name but in different domains, return all of them as result instead of just one. * 7634: intersphinx: references on the file in sub directory are broken * 9737: LaTeX: hlist is rendered as a list containing "aggedright" text * 9678: linkcheck: file extension was shown twice in warnings * 9697: py domain: An index entry with parens was registered for ``py:method`` directive with ``:property:`` option * 9775: py domain: Literal typehint was converted to a cross reference when :confval:`autodoc_typehints='description'` * 9708: needs_extension failed to check double-digit version correctly * 9688: Fix :rst:dir:`code`` does not recognize ``:class:`` option * 9733: Fix for logging handler flushing warnings in the middle of the docs build * 9656: Fix warnings without subtype being incorrectly suppressed * Intersphinx, for unresolved references with an explicit inventory, e.g., ``proj:myFunc``, leave the inventory prefix in the unresolved text. ``` ### 4.2.0 ``` ===================================== Features added -------------- * 9445: autodoc: Support class properties * 9479: autodoc: Emit a warning if target is a mocked object * 9560: autodoc: Allow to refer NewType instances with module name in Python 3.10 or above * 9447: html theme: Expose the version of Sphinx in the form of tuple as a template variable ``sphinx_version_tuple`` * 9594: manpage: Suppress the title of man page if description is empty * 9445: py domain: ``:py:property:`` directive supports ``:classmethod:`` option to describe the class property * 9524: test: SphinxTestApp can take ``builddir`` as an argument * 9535: C and C++, support more fundamental types, including GNU extensions. Bugs fixed ---------- * 9608: apidoc: apidoc does not generate a module definition for implicit namespace package * 9504: autodoc: generate incorrect reference to the parent class if the target class inherites the class having ``_name`` attribute * 9537, 9589: autodoc: Some objects under ``typing`` module are not displayed well with the HEAD of 3.10 * 9487: autodoc: typehint for cached_property is not shown * 9509: autodoc: AttributeError is raised on failed resolving typehints * 9518: autodoc: autodoc_docstring_signature does not effect to ``__init__()`` and ``__new__()`` * 9522: autodoc: PEP 585 style typehints having arguments (ex. ``list[int]``) are not displayed well * 9481: autosummary: some warnings contain non-existing filenames * 9568: autosummary: summarise overlined sectioned headings correctly * 9600: autosummary: Type annotations which contain commas in autosummary table are not removed completely * 9481: c domain: some warnings contain non-existing filenames * 9481: cpp domain: some warnings contain non-existing filenames * 9456: html search: abbreation marks are inserted to the search result if failed to fetch the content of the page * 9617: html search: The JS requirement warning is shown if browser is slow * 9267: html theme: CSS and JS files added by theme were loaded twice * 9585: py domain: ``:type:`` option for :rst:dir:`py:property` directive does not create a hyperlink * 9576: py domain: Literal typehint was converted to a cross reference * 9535 comment: C++, fix parsing of defaulted function parameters that are function pointers. * 9564: smartquotes: don't adjust typography for text with language-highlighted ``:code:`` role. * 9512: sphinx-build: crashed with the HEAD of Python 3.10 ```Links
- PyPI: https://pypi.org/project/sphinx - Changelog: https://pyup.io/changelogs/sphinx/ - Homepage: https://www.sphinx-doc.org/