Sphinx is a tool that facilitates creating documentation for Python
projects (or other documents consisting of multiple reStructuredText
sources). It was originally created for the Python documentation, and
supports Python project documentation well, but C/C++ is likewise
supported.
Sphinx uses reStructuredText as its markup language. Sphinx draws from
the parsing and translating suite, the Docutils.
Provides
Requires
License
BSD-2-Clause
Changelog
* Fri Oct 30 2026 Markéta Machová <mmachova@suse.com>
- Update to 9.2.0
* Fixed support for Python 3.16 alpha 0
* PDF build crash since LaTeX June 2026 release if tables are styled
with 'colorrows'
* Fix JavaScript search for languages whose stemmer class name does
not match the language name
* Drop Python 3.12 support
* Support Docutils 0.23
- Drop cpython-autodoc.patch and tests.patch, no longer needed
* Mon Oct 12 2026 Markéta Machová <mmachova@suse.com>
- Add upstream cpython-autodoc.patch to fix tests
* Thu Aug 20 2026 Nico Krapp <nico.krapp@suse.com>
- Apply tests.patch to fix tests with Pygments 2.21.0
* Fri Jul 24 2026 Steve Kowalik <steven.kowalik@suse.com>
- Update to 9.1.0:
[#]# Dependencies
* Drop Python 3.11 support.
* Drop Docutils 0.20 support.
* Support Docutils 0.22.
[#]# Incompatible changes
* SphinxComponentRegistry.create_source_parser() no longer has an app
parameter, instead taking config and env.
* Non-decodable characters in source files now raise an error.
* sphinx.ext.autodoc has been substantially rewritten, and there may be
some incompatible changes in edge cases, especially when extensions
interact with autodoc internals.
* Don’t include escaped title content in the search index.
[#]# Deprecated
* Deprecate remaining public .app attributes, including builder.app,
env.app, events.app, and SphinxTransform.app.
* Deprecate the set_application() method of Parser objects.
* Deprecate the Parser.config and env attributes.
* Deprecate support for non-UTF 8 source encodings, scheduled for removal
in Sphinx 10.
* Deprecate sphinx.io. Sphinx no longer uses the sphinx.io classes, having
replaced them with standard Python I/O. The entire sphinx.io module will
be removed in Sphinx 10.
* sphinx.environment.adapters.toctree.global_toctree_for_doc() and
sphinx.environment.BuildEnvironment.get_and_resolve_doctree() will
require a tags keyword argument from Sphinx 11.
[#]# Features added
* Add add_static_dir() for copying static assets from extensions to the
build output.
* Add doctest_fail_fast option to exit after the first failed test.
* linkcheck: Permit warning on every redirect with
linkcheck_allowed_redirects = {}.
* Support C domain objects in the table of contents.
* LaTeX: add support for fontawesome6 package.
* autodoc: Detect typing_extensions.overload and final() decorators.
* LaTeX: allow more cases of table nesting.
* LaTeX: support CSS3 length units.
* intersphinx: Add a file-based cache for remote inventories.
* LaTeX: add support for fontawesome7 package.
* autodoc: Initial support for PEP 695 type aliases.
* Add the new mathjax_config_path option to load MathJax configuration from
a file.
* linkcheck: Add the linkcheck_case_insensitive_urls option to allow
case-insensitive URL comparison for specific URL patterns.
* autosummary: Provide more context in import exception stack traces.
* Add config options to sphinx.ext.duration.
* Use MathJax v4 by default in the sphinx.ext.mathjax extension, from v3
previously.
* intersphinx: Fix error in format string interpolation.
* Add source_code_parser type to suppress_warnings for grouping issues
related to the C and C++ parsers.
[#]# Bugs fixed
* autodoc: Fix duplicate :no-index-entry: for modules.
* Fix compatibility with MyST-Parser.
* Fix tests for Python 3.15.
* autodoc: Fix default option parsing.
* Remove incorrect static typing assertions.
* LaTeXTranslator fails to build documents using the "acronym" standard
role.
* LaTeX: Fix rendering for grid filled merged vertical cell.
* LaTeX: Fix overrun footer for cases of merged vertical table cells.
* Fix creating HTMLThemeFactory objects in third-party extensions.
* LaTeX: PDF build crashes if a code-block contains more than circa 1350
codelines (about 27 a4-sized pages at default pointsize).
* LaTeX: TABs ending up in sphinxVerbatim fail to obey tab stops.
* autodoc: Improve support for non-weakreferencable objects.
* autodoc: Restore some missing exports in sphinx.ext.autodoc.
* autodoc: Restore sphinx.ext.autodoc.mock.
* autodoc: Restore the mapping interface for options objects.
* autodoc: Deprecate the mapping interface for options objects.
* multiple py:type directives for the same canonical type no longer result
in spurious duplicate object description warnings.
* LaTeX: tables using longtable raise error if tabularcolumns specifies
automatic widths (L, R, C, or J).
* LaTeX: when assigning longtable class to table for PDF, it may render
horizontally and overflow in right margin.
* LaTeX: adding a footnote to a longtable cell causes table to occupy full
width.
* LaTeX: Table in cell fails to build if it has many rows.
* LaTeX: longtable does not allow nested table.
* LaTeX: links in table captions do not work in PDF.
* LaTeX: URLs/links in section titles should render in PDF.
* Correctly parse and cross-reference unpacked type annotations.
* Add tilde ~ prefix support for py:deco.
* LaTeX: table nested in a merged cell leads to invalid LaTeX mark-up.
* LaTeX: possible duplicated footnotes in PDF from object signatures.
* LaTeX: if a cell contains a table, row coloring is turned off for the
next table cells.
* gettext: Correctly ignore trailing backslashes.
* intersphinx: Don’t add “v” prefix to non-numeric versions.
* Autodoc: Allow type aliases defined in the project to be properly
cross-referenced when used as type annotations.
* doctest: doctest blocks are now correctly added to a group defined by the
configuration variable doctest_test_doctest_blocks.
* Coverage builder: Fix TypeError when warning about missing modules.
* autoclass: parent class members no longer considered directly defined in
certain cases, depending on autodoc processing order.
* LaTeX: page break can separate admonition title from contents.
* Fix autodoc_type_aliases when they appear in PEP 604 union syntax.
* autodoc: show traceback during import in human readable representation.
* Support images with data URIs that aren’t base64-encoded.
* autodoc: Fix handling of undefined names in annotations by using the
FORWARDREF annotationlib format.
* EPUB: unify path separators in manifest items to forward slashes.
* text builder: fix an infinite loop when processing CSV tables.
* Remove extra parentheses from js:function arguments and errors.
- Drop patches:
* autodoc.patch
* autosummary.patch
* typing.patch
* docutils022.patch
* docutils022plus.patch
* Mon Sep 22 2025 Daniel Garcia <daniel.garcia@suse.com>
- Add upstream patch docutils022plus.patch to fix compatibility with
docutils >= 0.22
gh#sphinx-doc/sphinx#13548
* Thu Sep 11 2025 Markéta Machová <mmachova@suse.com>
- Add upstream patches to fix tests with Python 3.14:
* autodoc.patch
* autosummary.patch
* typing.patch
- Proactively add upstream patch to fix tests with docutils 0.22:
* docutils022.patch
- Rename multibuild flavor 'test' to 'test+doc' to better reflect
the current behaviour
* Mon Aug 25 2025 Markéta Machová <mmachova@suse.com>
- Convert to libalternatives on SLE-16-based and newer systems
* Fri Mar 14 2025 Markéta Machová <mmachova@suse.com>
- Update to 8.2.3
* Correct spelling of highlighting_failure in warning sub-type.
* Restore support for using sphinx.testing.path paths with
sphinx.testing.fixtures
* viewcode: Fix importing modules more than once.
* Fix argument type for jieba.load_userdict().
* Add workaround for nbsphinx implicit imports.
* Ensure inline <script/> tags are written exactly once.
* Define _StrPath.__radd__().
* Fix _CurrentDocument membership testing with parent_symbol.
* Wed Mar 12 2025 Daniel Garcia <daniel.garcia@suse.com>
- Add missing dependency python-roman-numerals
* Tue Mar 11 2025 Dirk Müller <dmueller@suse.com>
- update to 8.2.0:
* #13000: Drop Python 3.10 support.
* #13044: Remove the internal and undocumented has_equations
data from the :py:class:`!MathDomain` domain. The
undocumented :py:meth:`!MathDomain.has_equations` method now
unconditionally returns True. These are replaced by the
has_maths_elements key of the page context dict. Patch by
Adam Turner.
* #13227: HTML output for sequences of keys in the
:rst:role:`kbd` role no longer uses a <kbd class="kbd
compound"> element to wrap the keys and separators, but
places them directly in the relevant parent node. This means
that CSS rulesets targeting kbd.compound or .kbd.compound
will no longer have any effect. Patch by Adam Turner.
* #13037: Deprecate the SingleHTMLBuilder.fix_refuris method.
Patch by James Addison.
* #13083, #13330: Un-deprecate sphinx.util.import_object. Patch
by Matthias Geier.
* #13173: Add a new duplicate_declaration warning type, with
duplicate_declaration.c and duplicate_declaration.cpp
subtypes. Patch by Julien Lecomte and Adam Turner.
* #11824: linkcode: Allow extensions to add support for a
domain by defining the keys that should be present. Patch by
Nicolas Peugnet.
* #13144: Add a class option to the :rst:dir:`autosummary`
directive. Patch by Tim Hoffmann.
* #13146: Napoleon: Unify the type preprocessing logic to allow
Google-style docstrings to use the optional and default
keywords. Patch by Chris Barrick.
* #13227: Implement the :rst:role:`kbd` role as a SphinxRole.
Patch by Adam Turner.
* #13065: Enable colour by default in when running on CI. Patch
by Adam Turner.
* #13230: Allow supressing warnings from the :rst:dir:`toctree`
directive when a glob pattern doesn't match any documents,
via the new toc.empty_glob warning sub-type. Patch by Slawek
Figiel.
* #9732: Add the new autodoc.mocked_object warnings sub-type.
Patch by Cyril Roelandt.
* #7630, #4824: autodoc: Use :file:`.pyi` type stub files to
auto-document native modules. Patch by Adam Turner, partially
based on work by Allie Fitter.
* #12975: Enable configuration of trailing commas in multi-line
signatures in the Python and Javascript domains, via the new
:confval:`python_trailing_comma_in_multi_line_signatures` and
:confval:`javascript_trailing_comma_in_multi_line_signatures`
configuration options.
* #13264: Rename the :rst:dir:`math` directive's nowrap option
to :rst:dir:`math:no-wrap`. Patch by Adam Turner.
* #13269: Added the option to disable the use of type comments
in via the new :confval:`autodoc_use_type_comments` option,
which defaults to True for backwards compatibility. The
default will change to False in Sphinx 10. Patch by Adam
Turner.
* #9732: Add the new ref.any warnings sub-type to allow
suppressing the ambiguous 'any' cross-reference warning.
Patch by Simão Afonso and Adam Turner.
* #13272: The Python and JavaScript module directives now
support the :no-index-entry: option. Patch by Adam Turner.
* #12233: autodoc: Allow directives to use :no-index-entry: and
include the :no-index: and :no-index-entry: options within
:confval:`autodoc_default_options`. Patch by Jonny Saunders
and Adam Turner.
* #13172: Add support for short signatures in autosummary.
Patch by Tim Hoffmann.
* #13271: Change the signature prefix for abstract methods in
the Python domain to abstractmethod from abstract. Patch by
Adam Turner.
* #13271: Support the :abstract: option for classes, methods,
and properties in the Python domain. Patch by Adam Turner.
* #12507: Add the :ref:`collapsible <collapsible-admonitions>`
option to admonition directives. Patch by Chris Sewell.
* #8191, #8159: Add :rst:dir:`inheritance-diagram:include-
subclasses` option to the :rst:dir:`inheritance-diagram`
directive. Patch by Walter Dörwald.
* #11995: autodoc: Add support for
:confval:`python_display_short_literal_types`. Patch by
Bénédikt Tran and Adam Turner.
* #13163: Always print the full context when Sphinx encounters
an internal error. Patch by Kevin Deldycke and Adam Turner.
* #13105: Introduce the :rst:role:`py:deco` role to cross-
reference decorator functions and methods in the Python
domain. Patch by Adam Turner.
* #9169: Add the :confval:`intersphinx_resolve_self` option to
resolve an intersphinx reference to the current project.
Patch by Jakob Lykke Andersen and Adam Turner.
* #11280: Add ability to skip a particular section using the
no-search class. Patch by Will Lachance.
* #13326: Remove hardcoding from handling
:class:`~sphinx.addnodes.productionlist` nodes in all
writers, to improve flexibility. Patch by Adam Turner.
* #13335: Use misc.highlighting_failure subtype for Pygments
unknown lexers. Patch by Bart Kamphorst.
* #13354: Insert abbreviation nodes (hover text) for
positional- and keyword-only separators in Python signatures.
Patch by Adam Turner.
* #13333: Add the :mod:`sphinx.ext.apidoc` extension, to
automate API documentation generation from Python modules.
Patch by Chris Sewell and Adam Turner.
* #12463: autosummary: Respect an empty module __all__. Patch
by Valentin Pratz
* #13060: HTML Search: use Map to store per-file term scores.
Patch by James Addison
* #13130: LaTeX docs: pdflatex index creation may fail for
index entries in French. See :confval:`latex_use_xindy`.
Patch by Jean-François B.
* #13152: LaTeX: fix a typo from v7.4.0 in a default for
\sphinxboxsetup. Patch by Jean-François B.
* #13096: HTML Search: check that query terms exist as
properties in term indices before accessing them.
* #11233: linkcheck: match redirect URIs against
:confval:`linkcheck_ignore` by overriding session-level
requests.get_redirect_target.
* #13195: viewcode: Fix issue where import paths differ from
the directory structure. Patch by Ben Egan and Adam Turner.
* #13188: autodoc: fix detection of class methods implemented
in C. Patch by Bénédikt Tran.
* #1810: Always copy static files when building, regardless of
whether any documents have changed since the previous build.
Patch by Adam Turner.
* #13201: autodoc: fix ordering of members when using groupwise
for :confval:`autodoc_member_order`. Class methods are now
rendered before static methods, which themselves are rendered
before regular methods and attributes. Patch by Bénédikt
Tran.
* #12975: Avoid rendering a trailing comma in C and C++ multi-
line signatures.
* #13178: autodoc: Fix resolution for pathlib types. Patch by
Adam Turner.
* #13136: autodoc: Correctly handle multiple inheritance. Patch
by Pavel Holica
* #13273, #13318: Properly convert command-line overrides for
Boolean types. Patch by Adam Turner.
* #13302, #13319: Use the correct indentation for continuation
lines in :rst:dir:`productionlist` directives. Patch by Adam
Turner.
* #13328: Fix parsing of PEP 695 functions with return
annotations. Patch by Bénédikt Tran. Initial work by Arash
Badie-Modiri.
* #13224: Correctness fixup for test_html_multi_line_copyright.
Patch by Colin Watson, applied by James Addison.
- drop pygments.patch (upstream)
* Fri Jan 17 2025 Markéta Machová <mmachova@suse.com>
- Add pygments.patch to fix tests with Pygments 2.19
* Wed Nov 20 2024 Dirk Müller <dmueller@suse.com>
- update to 8.1.3:
* #13013: Restore support for :func:`!cut_lines` with no object
type. Patch by Adam Turner.
* #13012: Expose :exc:`sphinx.errors.ExtensionError` in
sphinx.util for backwards compatibility. This will be removed
in Sphinx 9, as exposing the exception in sphinx.util was
never intentional. :exc:`!ExtensionError` has been part of
sphinx.errors since Sphinx 0.9. Patch by Adam Turner.
* #13006: Use the preferred https://www.cve.org/ URL for the
:rst:role:`:cve: <cve>` role. Patch by Hugo van Kemenade.
* #13007: LaTeX: Improve resiliency when the required
fontawesome or fontawesome5 packages are not installed. Patch
by Jean-François B.
* #12756: Add lower-bounds to the sphinxcontrib-* dependencies.
Patch by Adam Turner.
* #12833: Update the LaTeX parskip package from 2001 to 2018.
Patch by Jean-François B.
* #12763: Remove unused internal class sphinx.util.Tee. Patch
by Adam Turner.
* #12822: LaTeX: for Unicode engines, the :ref:`fvset` default
is changed to '\fvset{fontsize=auto}' from
'\fvset{fontsize=\small}'. Code-blocks are unchanged as
FreeMono is now loaded with Scale=0.9. An adjustment to
existing projects is needed only if they used a custom
:ref:`fontpkg` configuration and did not set :ref:`fvset`.
Patch by Jean-François B.
* #12875: Disable smartquotes for languages: zh_CN and zh_TW by
default. Patch by A. Rafey Khan.
* #12762: Deprecate sphinx.util.import_object. Use
:py:func:`importlib.import_module` instead. Patch by Adam
Turner.
* #12766: Deprecate sphinx.util.FilenameUniqDict and
sphinx.util.DownloadFiles. Patch by Adam Turner.
* #11328: Mention evaluation of templated content during
production of static output files. Patch by James Addison.
* #12704: LaTeX: make :dudir:`contents <table-of-contents>`,
:dudir:`topic`, and :dudir:`sidebar` directives separately
customizable for PDF output. Patch by Jean-François B. and
Bénédikt Tran.
* #12474: Support type-dependent search result highlighting via
CSS. Patch by Tim Hoffmann.
* #12652: LaTeX: Add :confval:`math_numsep` support to latex
builder. Patch by Thomas Fanning and Jean-François B.
* #12743: No longer exit on the first warning when
:option:`--fail-on-warning <sphinx-build --fail-on-warning>`
is used. Instead, exit with a non-zero status if any warnings
were generated during the build. Patch by Adam Turner.
* #12743: Add :option:`sphinx-build --exception-on-warning`, to
raise an exception when warnings are emitted during the
build. Patch by Adam Turner and Jeremy Maitin-Shepard.
* #12907: Add :confval:`html_last_updated_use_utc` to allow
using universal time (GMT/UTC) instead of local time for the
date-time supplied to :confval:`html_last_updated_fmt`. Patch
by Adam Turner.
* #12910: Copyright entries now support the '%Y' placeholder to
substitute the current year. This is helpful for reducing the
reliance on Python modules such as :py:mod:`time` or
:py:mod:`datetime` in :file:`conf.py`. See :ref:`the docs
<config-copyright>` for further detail. Patch by Adam Turner.
* #11781: Add roles for referencing CVEs (:rst:role:`:cve:
<cve>`) and CWEs (:rst:role:`:cwe: <cwe>`). Patch by Hugo van
Kemenade.
* #11809: Improve the formatting for RFC section anchors. Patch
by Jakub Stasiak and Adam Turner.
* #12852: Support a :attr:`.Builder.supported_linkcode`
attribute for builders to enable use of
:mod:`sphinx.ext.linkcode`-generated references. Patch by
James Knight.
* #12949: Print configuration options that differ from the
pickled environment. This can be helpful in diagnosing the
cause of a full rebuild. Patch by Adam Turner.
* #12514: intersphinx: fix the meaning of a negative value for
:confval:`intersphinx_cache_limit`. Patch by Shengyu Zhang.
* #12722: LaTeX: avoid TeX reporting Overfull \hbox from too
long strings in a codeline when the problem has actually been
solved thanks to :ref:`latexsphinxsetupforcewraps`. Patch by
Jean-François B.
* #12730: The UnreferencedFootnotesDetector transform has been
improved to more consistently detect unreferenced footnotes.
Note, the priority of the transform has been changed from 200
to 622, so that it now runs after the docutils Footnotes
resolution transform. Patch by Chris Sewell.
* #12778: LaTeX: let :ref:`'sphinxsetup' <latexsphinxsetup>`
div.topic_box-shadow key if used with only one dimension set
both x-offset and y-offset as per documentation. Patch by
Jean-François B.
* #12587: Do not warn when potential ambiguity detected during
Intersphinx resolution occurs due to duplicate targets that
differ case-insensitively. Patch by James Addison.
* #12639: Fix singular and plural search results text. Patch by
Hugo van Kemenade.
* #12645: Correctly support custom gettext output templates.
Patch by Jeremy Bowman.
* #12717: LaTeX: let :option:`-q <sphinx-build -q>` (quiet)
option for :program:`sphinx-build -M latexpdf` or
:program:`make latexpdf` (O=-q) get passed to
:program:`latexmk`. Let :option:`-Q <sphinx-build -Q>`
(silent) apply as well to the PDF build phase. Patch by Jean-
François B.
* #12744: LaTeX: Classes injected by a custom interpreted text
role now give rise to nested \DUrole's, rather than a single
one with comma separated classes. Patch by Jean-François B.
* #12831: LaTeX: avoid large voids sometimes occurring at page
bottoms. Patch by Jean-François B.
* #11970, #12551: singlehtml builder: make target URIs to be
same-document references in the sense of :rfc:`RFC 3986, §4.4
<3986#section-4.4>`, e.g., index.html#foo becomes #foo.
(note: continuation of a partial fix added in Sphinx 7.3.0)
Patch by James Addison (with reference to prior work by Eric
Norige).
* #12735: Fix PEP 695 generic classes LaTeX output formatting.
Patch by Jean-François B. and Bénédikt Tran.
* #12782: intersphinx: fix double forward slashes when
generating the inventory file URL (user-defined base URL of
an intersphinx project are left untouched even if they end
with double forward slashes). Patch by Bénédikt Tran.
* #12796: Enable parallel reading if requested, even if there
are fewer than 6 documents. Patch by Matthias Geier.
* #12844: Restore support for :noindex: for the
:rst:dir:`js:module` and :rst:dir:`py:module` directives.
Patch by Stephen Finucane.
* #12916: Restore support for custom templates named with the
legacy _t suffix during apidoc RST rendering (regression in
7.4.0). Patch by James Addison.
* #12451: Only substitute copyright notice years with values
from SOURCE_DATE_EPOCH for entries that match the current
system clock year, and disallow substitution of future years.
Patch by James Addison and Adam Turner.
* #12905: intersphinx: fix flipped use of
:confval:`intersphinx_cache_limit`, which always kept the
cache for positive values, and always refreshed it for
negative ones. Patch by Nico Madysa.
* #12888: Add a warning when document is included in multiple
toctrees and ensure deterministic resolution of global
toctree in parallel builds by choosing the lexicographically
greatest parent document. Patch by A. Rafey Khan
* #12995: Significantly improve performance when building the
search index for Chinese languages. Patch by Adam Turner.
* #12767: :py:meth:`.Builder.write` is typed as final, meaning
that the :event:`write-started` event may be relied upon by
extensions. A new :py:meth:`.Builder.write_documents` method
has been added to control how documents are written. This is
intended for builders that do not output a file for each
document. Patch by Adam Turner.
* #12141: Migrate from the deprecated karma JavaScript test
framework to the actively-maintained jasmine framework. Test
coverage is unaffected. Patch by James Addison.
* Sun Sep 01 2024 Christoph G <foss@grueninger.de>
- update to 8.0.2
* #12633: Drop Python 3.9 support.
* Remove deprecated functions from sphinx.util:
+ Removed sphinx.util.path_stabilize (use sphinx.util.osutil.path_stabilize).
+ Removed sphinx.util.display_chunk (use sphinx.util.display.display_chunk).
+ Removed sphinx.util.status_iterator (use sphinx.util.display.status_iterator).
+ Removed sphinx.util.SkipProgressMessage (use
sphinx.util.display.SkipProgressMessage).
+ Removed sphinx.util.progress_message (use
sphinx.util.display.progress_message).
+ Removed sphinx.util.epoch_to_rfc1123 (use sphinx.http_date.epoch_to_rfc1123).
+ Removed sphinx.util.rfc1123_to_epoch (use sphinx.http_date.rfc1123_to_epoch).
+ Removed sphinx.util.save_traceback (use sphinx.exceptions.save_traceback).
+ Removed sphinx.util.format_exception_cut_frames (use
sphinx.exceptions.format_exception_cut_frames).
+ Removed sphinx.util.xmlname_checker (use
sphinx.builders.epub3._XML_NAME_PATTERN).
+ Removed sphinx.util.osutil.cd() (use contextlib.chdir()).
+ Removed sphinx.util.typing.stringify() (use
sphinx.util.typing.stringify_annotation()).
* #12593: Raise an error for invalid html_sidebars values.
* #12593: Raise an error in Theme.get_config() for invalid sections.
* #11693: Remove support for old-style Makefile and make.bat output in
sphinx-quickstart.
* #11693: Remove the --no-use-make-mode, -M, --use-make-mode, and -m options
from sphinx-quickstart.
* Removed the tuple interface to sphinx.ext.autodoc.ObjectMember.
* #12630: Sphinx 8 makes two changes to the linkcheck configuration defaults:
+ linkcheck_allow_unauthorized is now False by default.
+ linkcheck_report_timeouts_as_broken is now False by default.
* #12597: Change the default of show_warning_types from False to True.
* #12083: Remove support for the old (2008–2010) Sphinx 0.5 and Sphinx 0.6
intersphinx_mapping format.
* #12096: Do not overwrite user-supplied files when copying assets unless
forced with force=True.
* #12646: Remove sphinx.util.inspect.isNewType(). Use isinstance(obj,
typing.NewType) instead on Python 3.10 and newer.
* Remove the long-deprecated (since Sphinx 2) alias to VersionChange in
sphinx.directives.other (Deprecated since Sphinx 2). Use
sphinx.domains.changeset.VersionChange directly.
* Thu Jul 18 2024 Dirk Müller <dmueller@suse.com>
- update to 7.4.5:
* #12593, #12600: Revert coercing the type of selected
:confval:`html_sidebars` values to a list. Log an error
message when string values are detected. Patch by Adam
Turner.
* #12594: LaTeX: since 7.4.0, :rst:dir:`seealso` and other
"light" admonitions now break PDF builds if they contain a
:dudir:`figure` directive; and also if they are contained in
a table cell (rendered by tabulary). Patch by Jean-François
B.
* #12585, #12586: Do not warn when an intersphinx inventory
contains case-insensitively ambiguous duplicate items. Patch
by James Addison.
* #12582: Restore support for list-styled
:confval:`source_suffix` values with extensions that register
parsers. Patch by Adam Turner.
* #12580, #12583: Resolve failures with the C domain on
incremental builds with Sphinx 7.3.7 and earlier. Patch by
Adam Turner.
* Fix invalid HTML when a rubric node with invalid heading-
level is used. Patch by Adam Turner.
* #12579, #12581: Restore support for typing.ParamSpec in
autodoc. Patch by Adam Turner.
* #12555: Drop Docutils 0.18.1 and Docutils 0.19 support. Patch
by Adam Turner.
* LaTeX: the xcolor package is now required (but is for example
part of Ubuntu texlive-latex-recommended which has always
been required).
* LaTeX: the fontawesome5 LaTeX package is needed for the
default choices of icons now used in admonition titles in PDF
output; but if unavailable the PDF build will simply silently
omit rendering such icons. Check the documentation of the
iconpackage key of :ref:`'sphinxsetup' <latexsphinxsetup>`
for more.
* LaTeX: the sphinxlightbox environment is not used anymore,
all types of admonitions use (by default) only
sphinxheavybox.
* #11165: Support the officially recommended .jinja suffix for
template files. Patch by James Addison and Adam Turner
* #11165: Support the officially recommended .jinja suffix for
template files. Patch by James Addison and Adam Turner
* #12325: Flatten Union[Literal[T], Literal[U], ...] to
Literal[T, U, ...] when turning annotations into strings.
Patch by Adam Turner.
* #12325: Flatten Union[Literal[T], Literal[U], ...] to
Literal[T, U, ...] when turning annotations into strings.
Patch by Adam Turner.
* #12319: sphinx.ext.extlinks: Add extlink-{name} CSS class to
links. Patch by Hugo van Kemenade.
* #12319: sphinx.ext.extlinks: Add extlink-{name} CSS class to
links. Patch by Hugo van Kemenade.
* #12387: Improve CLI progress message, when copying assets.
Patch by INADA Nakoi and Bénédikt Tran.
* #12387: Improve CLI progress message, when copying assets.
Patch by INADA Nakoi and Bénédikt Tran.
* #12361: Add :attr:`.BuildEnvironment.parser`. Patch by Chris
Sewell.
* #12361: Add :attr:`.BuildEnvironment.parser`. Patch by Chris
Sewell.
* #12358: Add :attr:`.Sphinx.fresh_env_used`. Patch by Chris
Sewell.
* #12358: Add :attr:`.Sphinx.fresh_env_used`. Patch by Chris
Sewell.
* #12329: Add detection of ambiguous std:label and std:term
references during loading and resolution of Intersphinx
targets. Patch by James Addison.
* #12329: Add detection of ambiguous std:label and std:term
references during loading and resolution of Intersphinx
targets. Patch by James Addison.
* #12422: Do not duplicate "navigation" in aria-label of built-
in themes. Patch by Thomas Weißschuh
* #12422: Do not duplicate "navigation" in aria-label of built-
in themes. Patch by Thomas Weißschuh
* #12421: Include project name in logo_alt of built-in themes.
Patch by Thomas Weißschuh
* #12421: Include project name in logo_alt of built-in themes.
Patch by Thomas Weißschuh
* #12448: Add :option:`sphinx-apidoc --remove-old` option.
Patch by Chris Sewell.
* #12448: Add :option:`sphinx-apidoc --remove-old` option.
Patch by Chris Sewell.
* #12456: Add :option:`sphinx-autogen --remove-old` option.
Patch by Chris Sewell.
* #12456: Add :option:`sphinx-autogen --remove-old` option.
Patch by Chris Sewell.
* #12479: Add warning subtype toc.no_title. Patch by Ondřej
Navrátil.
* #12479: Add warning subtype toc.no_title. Patch by Ondřej
Navrátil.
* #12492: Add helper methods for parsing reStructuredText
content into nodes from within a directive. :py:meth:`~sphin
x.util.docutils.SphinxDirective.parse_content_to_nodes()`
parses the directive's content and returns a list of Docutils
nodes. :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_
text_to_nodes()` parses the provided text and returns a list
of Docutils nodes. :py:meth:`~sphinx.util.docutils.SphinxDire
ctive.parse_inline()` parses the provided text into inline
elements and text nodes. Patch by Adam Turner.
* #12492: Add helper methods for parsing reStructuredText
content into nodes from within a directive.
* :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_content
_to_nodes()` parses the directive's content and returns a
list of Docutils nodes.
* :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_text_to
_nodes()` parses the provided text and returns a list of
Docutils nodes.
* :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_inline(
)` parses the provided text into inline elements and text
nodes.
* Patch by Adam Turner.
* #12258: Support typing_extensions.Unpack Patch by Bénédikt
Tran and Adam Turner.
* #12258: Support typing_extensions.Unpack Patch by Bénédikt
Tran and Adam Turner.
* #12524: Add a class option to the :rst:dir:`toctree`
directive. Patch by Tim Hoffmann.
* #12524: Add a class option to the :rst:dir:`toctree`
directive. Patch by Tim Hoffmann.
* #12536: Add the :rst:dir:`confval` directive. Patch by Adam
Turner.
* #12536: Add the :rst:dir:`confval` directive. Patch by Adam
Turner.
* #12537: :confval:`c_id_attributes`,
:confval:`c_paren_attributes`, :confval:`cpp_id_attributes`,
and :confval:`cpp_paren_attributes` can now be a tuple of
strings. :confval:`c_extra_keywords`,
:confval:`gettext_additional_targets`,
:confval:`html_domain_indices`,
:confval:`latex_domain_indices`, and
:confval:`texinfo_domain_indices`, can now be a set of
strings. Patch by Adam Turner.
* #12537: :confval:`c_id_attributes`,
:confval:`c_paren_attributes`, :confval:`cpp_id_attributes`,
and :confval:`cpp_paren_attributes` can now be a tuple of
strings. :confval:`c_extra_keywords`,
:confval:`gettext_additional_targets`,
:confval:`html_domain_indices`,
:confval:`latex_domain_indices`, and
:confval:`texinfo_domain_indices`, can now be a set of
strings. Patch by Adam Turner.
* #12523: Added configuration option, :confval:`math_numsep`,
to define the separator for math numbering. Patch by Thomas
Fanning
* #12523: Added configuration option, :confval:`math_numsep`,
to define the separator for math numbering. Patch by Thomas
Fanning
* #11592: Add :confval:`coverage_modules` to the coverage
builder to allow explicitly specifying which modules should
be documented. Patch by Stephen Finucane.
* #11592: Add :confval:`coverage_modules` to the coverage
builder to allow explicitly specifying which modules should
be documented. Patch by Stephen Finucane.
* #7896, #11989: Add a :rst:dir:`py:type` directive for
documenting type aliases, and a :rst:role:`py:type` role for
linking to them. Patch by Ashley Whetter.
* #7896, #11989: Add a :rst:dir:`py:type` directive for
documenting type aliases, and a :rst:role:`py:type` role for
linking to them. Patch by Ashley Whetter.
* #12549: Add optional description argument to
:meth:`.Sphinx.add_config_value`. Patch by Chris Sewell.
* #12549: Add optional description argument to
:meth:`.Sphinx.add_config_value`. Patch by Chris Sewell.
* #6792: Prohibit module import cycles in
:mod:`sphinx.ext.autosummary`. Patch by Trevor Bekolay.
* #6792: Prohibit module import cycles in
:mod:`sphinx.ext.autosummary`. Patch by Trevor Bekolay.
* #12508: LaTeX: Revamped styling of all admonitions, with
addition of a title row with icon. Patch by Jean-François B.
* #12508: LaTeX: Revamped styling of all admonitions, with
addition of a title row with icon. Patch by Jean-François B.
* #11773: Display :py:class:`~typing.Annotated` annotations
with their metadata in the Python domain. Patch by Adam
Turner and David Stansby.
* #11773: Display :py:class:`~typing.Annotated` annotations
with their metadata in the Python domain. Patch by Adam
Turner and David Stansby.
* #12506: Add heading-level option to :rst:dir:`rubric`
directive. Patch by Chris Sewell.
* #12506: Add heading-level option to :rst:dir:`rubric`
directive. Patch by Chris Sewell.
* #12567: Add the :event:`write-started` event. Patch by Chris
Sewell.
* #12567: Add the :event:`write-started` event. Patch by Chris
Sewell.
* #12314: Properly format collections.abc.Callable in
annotations. Patch by Adam Turner.
* #12162: Fix a performance regression in the C domain that has
been present since version 3.0.0. Patch by Donald Hunter.
* #12320: Fix removal of anchors from search summaries
(regression in 7.3.0). Patch by Will Lachance.
* #12251: Fix merge_domaindata() in sphinx.ext.duration. Patch
by Matthias Geier.
* #12224: Properly detect WebP files. Patch by Benjamin Cabé.
* #12380: LaTeX: Footnote mark sometimes indicates Page N where
N is the current page number and the footnote does appear on
that same page. Patch by Jean-François B.
* #12410: LaTeX: for French and 'lualatex' as
:confval:`latex_engine` polyglossia and not babel is used
(contrarily to 'xelatex'). Patch by Jean-François B.
* #12416: Ensure that configuration setting aliases are always
synchronised when one value or the other is modified. Patch
by Bénédikt Tran.
* #12220: Fix loading custom template translations for en
locale. Patch by Nicolas Peugnet.
* #12459: Add valid-type arguments to the
linkcheck_rate_limit_timeout configuration setting. Patch by
James Addison.
* #12331: Resolve data-URI-image-extraction regression from
v7.3.0 affecting builders without native support for data-
URIs in their output format. Patch by James Addison.
* #12494: Fix invalid genindex.html file produced with
translated docs (regression in 7.1.0). Patch by Nicolas
Peugnet.
* #11961: Omit anchor references from document title entries in
the search index, removing duplication of search results.
Patch by James Addison.
* #12425: Use Docutils' SVG processing in the HTML builder and
remove Sphinx's custom logic. Patch by Tunç Başar Köse.
* #12391: Adjust scoring of matches during HTML search so that
document main titles tend to rank higher than subsection
titles. In addition, boost matches on the name of programming
domain objects relative to title/subtitle matches. Patch by
James Addison and Will Lachance.
* #9634: Do not add a fallback language by stripping the
country code. Patch by Alvin Wong.
* #12352: Add domain objects to the table of contents in the
same order as defined in the document. Previously, each
domain used language-specific nesting rules, which removed
control from document authors. Patch by Ja