Up to [cvs.NetBSD.org] / pkgsrc / textproc / py-sphinx
Request diff between arbitrary revisions
Keyword substitution: kv
Default branch: MAIN
py-sphinx: update to 9.0.4.
Release 9.0.4 (released Dec 04, 2025)
Bugs fixed
#14143: Fix spurious build warnings when translators reorder references in strings, or use translated display text in references. Patch by Matt Wang.
Release 9.0.3 (released Dec 04, 2025)
Bugs fixed
#14142: autodoc: Restore some missing exports in sphinx.ext.autodoc. Patch by Adam Turner.
Release 9.0.2 (released Dec 03, 2025)
Bugs fixed
#14142: autodoc: Restore sphinx.ext.autodoc.mock. Patch by Adam Turner.
Release 9.0.1 (released Dec 01, 2025)
Bugs fixed
#13942: autodoc: Restore the mapping interface for options objects. Patch by Adam Turner.
#13942: autodoc: Deprecate the mapping interface for options objects. Patch by Adam Turner.
#13387: Update translations.
Release 9.0.0 (released Nov 30, 2025)
Dependencies
#13786: Support Docutils 0.22. Patch by Adam Turner.
Incompatible changes
#13639: SphinxComponentRegistry.create_source_parser() no longer has an app parameter, instead taking config and env. Patch by Adam Turner.
#13679: Non-decodable characters in source files now raise an error. Such bytes have been replaced with ‘?’ along with logging a warning since Sphinx 2.0. Patch by Adam Turner.
#13751, #14089: sphinx.ext.autodoc has been substantially rewritten, and there may be some incompatible changes in edge cases, especially when extensions interact with autodoc internals. The autodoc_use_legacy_class_based option has been added to use the legacy (pre-9.0) implementation of autodoc. Patches by Adam Turner.
#13355: Don’t include escaped title content in the search index. Patch by Will Lachance.
Deprecated
13627: Deprecate remaining public .app attributes, including builder.app, env.app, events.app, and SphinxTransform.app. Patch by Adam Turner.
#13637: Deprecate the set_application() method of Parser objects. Patch by Adam Turner.
#13644: Deprecate the Parser.config and env attributes. Patch by Adam Turner.
#13665: Deprecate support for non-UTF 8 source encodings, scheduled for removal in Sphinx 10. Patch by Adam Turner.
#13682: 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. Patch by Adam Turner.
#13631: 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. It may optionally be passed from Sphinx 9 onwards. Patch by Adam Turner.
Features added
#13332: Add doctest_fail_fast option to exit after the first failed test. Patch by Till Hoffmann.
#13439: linkcheck: Permit warning on every redirect with linkcheck_allowed_redirects = {}. Patch by Adam Turner and James Addison.
#13497: Support C domain objects in the table of contents.
#13500: LaTeX: add support for fontawesome6 package. Patch by Jean-François B.
#13509: autodoc: Detect typing_extensions.overload and final() decorators. Patch by Spencer Brown.
#13535: html search: Update to the latest version of Snowball (v3.0.1). Patch by Adam Turner.
#13647: LaTeX: allow more cases of table nesting. Patch by Jean-François B.
#13657: LaTeX: support CSS3 length units. Patch by Jean-François B.
#13684: intersphinx: Add a file-based cache for remote inventories. The location of the cache directory must not be relied upon externally, as it may change without notice or warning in future releases. Patch by Adam Turner.
#13805: LaTeX: add support for fontawesome7 package. Patch by Jean-François B.
#13508: autodoc: Initial support for PEP 695 type aliases. Patch by Martin Matouš, Jeremy Maitin-Shepard, and Adam Turner.
#14023: Add the new mathjax_config_path option to load MathJax configuration from a file. Patch by Randolf Scholz and Adam Turner.
#14046: linkcheck: Add the linkcheck_case_insensitive_urls option to allow case-insensitive URL comparison for specific URL patterns. This is useful for links to websites that normalise URL casing (e.g. GitHub) or case-insensitive servers. Patch by Fazeel Usmani and James Addison.
#14075: autosummary: Provide more context in import exception stack traces. Patch by Philipp A.
#13468: Add config options to sphinx.ext.duration. Patch by Erik Bedard and Adam Turner.
#14022: Use MathJax v4 by default in the sphinx.ext.mathjax extension, from v3 previously. To keep using an older version, set the mathjax_path option. Also add the new mathjax4_config option to configure MathJax v4. Note that MathJax v3 is mostly compatible with MathJax v4, so existing mathjax3_config settings should not need to change. Patch by Matthias Geier.
#14029: intersphinx: Fix error in format string interpolation. Patch by Matthieu de Cibeins.
#13894: Add source_code_parser type to suppress_warnings for grouping issues related to the C and C++ parsers. Patch by Valentin H.
Bugs fixed
#13926: multiple py:type directives for the same canonical type no longer result in spurious duplicate object description warnings. Patch by Jeremy Maitin-Shepard.
#1327: LaTeX: tables using longtable raise error if tabularcolumns specifies automatic widths (L, R, C, or J). Patch by Jean-François B.
#3447: LaTeX: when assigning longtable class to table for PDF, it may render “horizontally” and overflow in right margin. Patch by Jean-François B.
#8828: LaTeX: adding a footnote to a longtable cell causes table to occupy full width. Patch by Jean-François B.
#11498: LaTeX: Table in cell fails to build if it has many rows. Patch by Jean-François B.
#11515: LaTeX: longtable does not allow nested table. Patch by Jean-François B.
#11973: LaTeX: links in table captions do not work in PDF. Patch by Jean-François B.
#12821: LaTeX: URLs/links in section titles should render in PDF. Patch by Jean-François B.
#13369: Correctly parse and cross-reference unpacked type annotations. Patch by Alicia Garcia-Raboso.
#13528: Add tilde ~ prefix support for py:deco. Patch by Shengyu Zhang and Adam Turner.
#13597: LaTeX: table nested in a merged cell leads to invalid LaTeX mark-up and PDF cannot be built. Patch by Jean-François B.
#13619: LaTeX: possible duplicated footnotes in PDF from object signatures (typically if latex_show_urls = 'footnote'). Patch by Jean-François B.
#13635: LaTeX: if a cell contains a table, row coloring is turned off for the next table cells. Patch by Jean-François B.
#13685: gettext: Correctly ignore trailing backslashes. Patch by Bénédikt Tran.
#13712: intersphinx: Don’t add “v” prefix to non-numeric versions. Patch by Szymon Karpinski.
#13688: HTML builder: Replace <em class="property"> with <span class="property"> for attribute type annotations to improve semantic HTML structure. Patch by Mark Ostroth.
#13812 (discussion): LaTeX: long confval value does not wrap at spaces in PDF. Patch by Jean-François B.
#10785: Autodoc: Allow type aliases defined in the project to be properly cross-referenced when used as type annotations. This makes it possible for objects documented as :py:data: to be hyperlinked in function signatures.
#13858: doctest: doctest blocks are now correctly added to a group defined by the configuration variable doctest_test_doctest_blocks.
#13885: Coverage builder: Fix TypeError when warning about missing modules. Patch by Damien Ayers.
#13929: Duplicate equation label warnings now have a new warning sub-type, ref.equation. Patch by Jared Dillard.
#13935: autoclass: parent class members no longer considered directly defined in certain cases, depending on autodoc processing order. Patch by Jeremy Maitin-Shepard.
#13939: LaTeX: page break can separate admonition title from contents. Patch by Jean-François B.
#14004: Fix autodoc_type_aliases when they appear in PEP 604 union syntax (Alias | Type). Patch by Tamika Nomara.
#14059: LaTeX: Footnotes cause pdflatex error with French language (since late June 2025 upstream change to LaTeX babel-french). Patch by Jean-François B.
#13916: HTML Search: do not clear text fragments from the URL on page load. Patch by Harmen Stoppels.
#13944: autodoc: show traceback during import in human readable representation. Patch by Florian Best.
#14006: Support images with data URIs that aren’t base64-encoded. Patch by Shengyu Zhang and Adam Turner.
#12797: Fix Some type variables (...) are not listed in Generic[...] TypeError when inheriting from both Generic and autodoc mocked class. Patch by Ikor Jefocur and Daniel Sperber.
#13945: autodoc: Fix handling of undefined names in annotations by using the FORWARDREF annotationlib format. Patch by Rui Pinheiro and Adam Turner.
#14067: EPUB: unify path separators in manifest items to forward slashes; resolve duplicates in the manifest on Windows. Patch by Akihiro Takizawa.
#13741: text builder: fix an infinite loop when processing CSV tables. Patch by Bénédikt Tran.
#13217: Remove extra parentheses from js:function arguments and errors. Patch by Shengyu Zhang.
py-sphinx: update to 8.2.1. Release 8.2.1 (released Feb 21, 2025) ===================================== Bugs fixed ---------- * #13367: Correct spelling of ``highlighting_failure`` in warning sub-type. Patch by Bart Kamphorst. * #13377: Restore support for using ``sphinx.testing.path`` paths with ``sphinx.testing.fixtures``. Patch by Kazuya Takei. * #13380: viewcode: Fix importing modules more than once. Patch by Dave Hoese. * #13382: Napoleon: Use the right valid types for configuration values. Patch by Adam Turner. * 13376: Fix copying assets from a relative :confval:`html_static_path` entry. Patch by Adam Turner. Release 8.2.0 (released Feb 18, 2025) ===================================== Dependencies ------------ * #13000: Drop Python 3.10 support. Incompatible changes -------------------- * #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. Deprecated ---------- * #13037: Deprecate the ``SingleHTMLBuilder.fix_refuris`` method. Patch by James Addison. * #13083, #13330: Un-deprecate ``sphinx.util.import_object``. Patch by Matthias Geier. Features added -------------- * #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. Bugs fixed ---------- * #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. Testing ------- * #13224: Correctness fixup for ``test_html_multi_line_copyright``. Patch by Colin Watson, applied by James Addison.
py-sphinx: update to 8.1.2.
Release 8.1.2 (released Oct 12, 2024)
=====================================
Bugs fixed
----------
* #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.
Release 8.1.1 (released Oct 11, 2024)
=====================================
Bugs fixed
----------
* #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.
Release 8.1.0 (released Oct 10, 2024)
=====================================
Dependencies
------------
* #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.
Incompatible changes
--------------------
* #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.
Deprecated
----------
* #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.
Features added
--------------
* #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.
Bugs fixed
----------
* #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.
Testing
-------
* #12141: Migrate from the deprecated ``karma`` JavaScript test framework to
the actively-maintained ``jasmine`` framework. Test coverage is unaffected.
Patch by James Addison.
py-sphinx: update to 8.0.2.
Release 8.0.2 (released Jul 30, 2024)
=====================================
Bugs fixed
----------
* Fix the ``pygments.Formatter.__class_getitem__`` patch.
Patch by Adam Turner.
Release 8.0.1 (released Jul 30, 2024)
=====================================
Bugs fixed
----------
* Patch ``pygments.Formatter.__class_getitem__`` in Pygments 2.17.
Patch by Adam Turner.
Release 8.0.0 (released Jul 29, 2024)
=====================================
Dependencies
------------
* #12633: Drop Python 3.9 support.
Incompatible changes
--------------------
.. rst-class:: compact
* 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``).
Patch by Adam Turner.
* Removed :py:func:`!sphinx.util.osutil.cd`
(use :py:func:`contextlib.chdir`).
Patch by Adam Turner.
* Removed :py:func:`!sphinx.util.typing.stringify`
(use :py:func:`!sphinx.util.typing.stringify_annotation`).
Patch by Adam Turner.
* #12593: Raise an error for invalid :confval:`html_sidebars` values.
Patch by Adam Turner.
* #12593: Raise an error in :py:func:`!Theme.get_config` for invalid sections.
Patch by Adam Turner.
* #11693: Remove support for old-style :file:`Makefile` and :file:`make.bat`
output in :program:`sphinx-quickstart`.
* #11693: Remove the :option:`!--no-use-make-mode`, :option:`!-M`,
:option:`!--use-make-mode`, and :option:`!-m` options
from :program:`sphinx-quickstart`.
Patch by Adam Turner.
* Removed the tuple interface to :py:class:`!sphinx.ext.autodoc.ObjectMember`.
Patch by Adam Turner.
* #12630: Sphinx 8 makes two changes to the ``linkcheck`` configuration defaults:
* :confval:`linkcheck_allow_unauthorized` is now ``False`` by default.
* :confval:`linkcheck_report_timeouts_as_broken` is now ``False`` by default.
Patch by James Addison.
* #12597: Change the default of :confval:`show_warning_types`
from ``False`` to ``True``.
Patch by Chris Sewell.
* #12083: Remove support for the old (2008--2010) Sphinx 0.5 and Sphinx 0.6
:confval:`intersphinx_mapping` format.
Patch by Bénédikt Tran and Adam Turner.
* #12096: Do not overwrite user-supplied files when copying assets
unless forced with ``force=True``.
Patch by Adam Turner.
* #12646: Remove :py:func:`!sphinx.util.inspect.isNewType`.
Use ``isinstance(obj, typing.NewType)`` instead on Python 3.10 and newer.
Patch by Adam Turner.
* Remove the long-deprecated (since Sphinx 2) alias
to :py:class:`!VersionChange` in
:py:mod:`!sphinx.directives.other`
(Deprecated since Sphinx 2).
Use :py:class:`!sphinx.domains.changeset.VersionChange` directly.
Patch by Adam Turner.
Deprecated
----------
* #12643: Renamed ``sphinx.ext.intersphinx.normalize_intersphinx_mapping``
to ``sphinx.ext.intersphinx.validate_intersphinx_mapping``.
The old name will be removed in Sphinx 10.
Patch by Adam Turner.
* #12650, #12686, #12690: Extend the deprecation for string methods on
:py:class:`~pathlib.Path` objects to Sphinx 9.
Use :py:func:`os.fspath` to convert :py:class:`~pathlib.Path` objects to strings,
or :py:class:`~pathlib.Path`'s methods to work with path objects.
Patch by Adam Turner.
py-sphinx: update to 7.4.7.
Release 7.4.7 (released Jul 20, 2024)
=====================================
Bugs fixed
----------
* #12096: Warn when files are overwritten in the build directory.
Patch by Adam Turner and Bénédikt Tran.
* #12620: Ensure that old-style object description options are respected.
Patch by Adam Turner.
* #12601, #12625: Support callable objects in :py:class:`~typing.Annotated` type
metadata in the Python domain.
Patch by Adam Turner.
* #12601, #12622: Resolve :py:class:`~typing.Annotated` warnings with
``sphinx.ext.autodoc``,
especially when using :mod:`dataclasses` as type metadata.
Patch by Adam Turner.
* #12589, #12626: autosummary: Fix warnings with :rst:role:`!autolink`.
Patch by Adam Turner.
Release 7.4.6 (released Jul 18, 2024)
=====================================
Bugs fixed
----------
* #12589, #9743, #12609: autosummary: Do not add the package prefix when
generating autosummary directives for modules within a package.
Patch by Adam Turner.
* #12613: Reduce log severity for ambiguity detection during inventory loading.
Patch by James Addison.
Release 7.4.5 (released Jul 16, 2024)
=====================================
Bugs fixed
----------
* #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.
Release 7.4.4 (released Jul 15, 2024)
=====================================
Bugs fixed
----------
* #12585, #12586: Do not warn when an intersphinx inventory contains
case-insensitively ambiguous duplicate items.
Patch by James Addison.
Release 7.4.3 (released Jul 15, 2024)
=====================================
Bugs fixed
----------
* #12582: Restore support for list-styled :confval:`source_suffix` values
with extensions that register parsers.
Patch by Adam Turner.
Release 7.4.2 (released Jul 15, 2024)
=====================================
Bugs fixed
----------
* #12580, #12583: Resolve failures with the C domain on incremental builds
with Sphinx 7.3.7 and earlier.
Patch by Adam Turner.
Release 7.4.1 (released Jul 15, 2024)
=====================================
Bugs fixed
----------
* 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.
Release 7.4.0 (released Jul 15, 2024)
=====================================
Dependencies
------------
* #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.
Deprecated
----------
* LaTeX: the ``sphinxlightbox`` environment is not used anymore, all types
of admonitions use (by default) only ``sphinxheavybox``.
Features added
--------------
.. rst-class:: compact
* #11165: Support the `officially recommended`_ ``.jinja`` suffix for template
files.
Patch by James Addison and Adam Turner
.. _officially recommended: https://jinja.palletsprojects.com/en/latest/templates/#template-file-extension
* #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.
* #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.
* #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.
* #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
* #12448: Add :option:`sphinx-apidoc --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.
* #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.
* #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.
* #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
* #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.
* #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.
* #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.
* #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.
Bugs fixed
----------
* #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: Avoid footnote markers ``Page N`` when ``N`` is already
the current page number.
Patch by Jean-François B.
* #12410: LaTeX: for French and ``'lualatex'`` as :confval:`latex_engine`
use ``babel`` as with ``'xelatex'`` (and not ``polyglossia``).
Patch by Jean-François B.
* #12520: LaTeX: let :rst:dir:`todolist` produce correct hyperlinks in PDF.
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 Jakob Lykke Andersen and Adam Turner.
* #11041: linkcheck: Ignore URLs that respond with non-Unicode content.
Patch by James Addison.
* #12543: Fix :pep:`695` formatting for LaTeX output.
Patch by Bénédikt Tran.
Testing
-------
* karma: refactor HTML search tests to use fixtures generated by Sphinx.
Patch by James Addison.
py-sphinx: update to 7.3.7. Release 7.3.7 (released Apr 19, 2024) ===================================== Bugs fixed ---------- * #12299: Defer loading themes defined via entry points until their explicit use by the user or a child theme. Patch by Adam Turner. * #12305: Return the default value for ``theme.get_config()`` with an unsupported theme configuration section. Patch by Adam Turner. Release 7.3.6 (released Apr 17, 2024) ===================================== Bugs fixed ---------- * #12295: Re-export all AST types in the C and C++ domains. Patch by Adam Turner. * #12295: Re-export various objects from ``sphinx.domains.python._annotations`` in ``sphinx.domains.python``. Patch by Jacob Chesslo and Adam Turner. Release 7.3.5 (released Apr 17, 2024) ===================================== Bugs fixed ---------- * #12295: Re-export various objects from ``sphinx.domains.python._object`` in ``sphinx.domains.python``. Patch by Jacob Chesslo and Adam Turner. Release 7.3.4 (released Apr 17, 2024) ===================================== Bugs fixed ---------- * Handle cases when ``Any`` is not an instance of ``type``. Patch by Adam Turner. Release 7.3.3 (released Apr 17, 2024) ===================================== Bugs fixed ---------- * #12290: Fix a false-positive warning when setting a configuration value with ``Any`` as the valid type to a type other than the value's default. Patch by Adam Turner. Release 7.3.2 (released Apr 17, 2024) ===================================== Bugs fixed ---------- * Preload all themes defined via entry points. Patch by Adam Turner. * Fix a bad interaction between the ``'Furo'`` theme and the new-style for configuration values. Patch by Adam Turner. Release 7.3.1 (released Apr 17, 2024) ===================================== Dependencies ------------ * Require ``tomli`` on Python 3.10 and earlier. Patch by Adam Turner. Release 7.3.0 (released Apr 16, 2024) ===================================== Dependencies ------------ * #11858: Increase the minimum supported version of Alabaster to 0.7.14. Patch by Adam Turner. * #11411: Support `Docutils 0.21`_. Patch by Adam Turner. .. _Docutils 0.21: https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09 * #12012: Use ``types-docutils`` instead of ``docutils-stubs``. Deprecated ---------- * #11693: Support for old-style :file:`Makefile` and :file:`make.bat` output in :program:`sphinx-quickstart`, and the associated options :option:`!-M`, :option:`!-m`, :option:`!--no-use-make-mode`, and :option:`!--use-make-mode`. * #11285: Direct access to :attr:`!sphinx.testing.util.SphinxTestApp._status` or :attr:`!sphinx.testing.util.SphinxTestApp._warning` is deprecated. Use the public properties :attr:`!sphinx.testing.util.SphinxTestApp.status` and :attr:`!sphinx.testing.util.SphinxTestApp.warning` instead. Patch by Bénédikt Tran. * tests: :func:`!sphinx.testing.util.strip_escseq` is deprecated in favour of :func:`!sphinx.util.console.strip_colors`. Patch by Bénédikt Tran. Features added -------------- * #12265: Support theme configuration via ``theme.toml``. * #11701: HTML Search: Adopt the new `\<search\>`_ element. Patch by Bénédikt Tran. .. _`\<search\>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/search * #11776: Add long option names to ``sphinx-build``. Patch by Hugo van Kemenade, Adam Turner, Bénédikt Tran, and Ezio Melotti. * Organise the ``sphinx-build`` options into groups. Patch by Adam Turner. * #11855: Defer computation of configuration values. Patch by Adam Turner. * Add ``:no-search:`` as an alias of the ``:nosearch:`` metadata field. Patch by Adam Turner. * #11803: autodoc: Use an overriden ``__repr__()`` function in an enum, if defined. Patch by Shengyu Zhang. * #11825: Allow custom targets in the manpage role. Patch by Nicolas Peugnet. * #11892: Improved performance when resolving cross references in the C++ domain. Patch by Rouslan Korneychuk. * #11905: Add a :rst:dir:`versionremoved` directive. Patch by Hugo van Kemenade, Adam Turner, and C.A.M. Gerlach. * #11981: Improve rendering of signatures using ``slice`` syntax, e.g., ``def foo(arg: np.float64[:,:]) -> None: ...``. * The manpage builder now adds `OSC 8`_ anchors to hyperlinks, using the `groff`_ device control command. .. _OSC 8: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda .. _groff: https://lists.gnu.org/archive/html/groff/2021-10/msg00000.html * #11015: Change the text of the :rst:dir:`versionadded` directive from ``New in [...]`` to ``Added in [...]``. Patch by Bénédikt Tran. * #12131: Added :confval:`show_warning_types` configuration option. Patch by Chris Sewell. * #12193: Improve ``external`` warnings for unknown roles. In particular, suggest related role names if an object type is mistakenly used. Patch by Chris Sewell. * Add public type alias :class:`sphinx.util.typing.ExtensionMetadata`. This can be used by extension developers to annotate the return type of their ``setup`` function. Patch by Chris Sewell. Bugs fixed ---------- * #11668: Raise a useful error when ``theme.conf`` is missing. Patch by Vinay Sajip. * #11622: Ensure that the order of keys in ``searchindex.js`` is deterministic. Patch by Pietro Albini. * #11617: ANSI control sequences are stripped from the output when writing to a warnings file with :option:`-w <sphinx-build -w>`. Patch by Bénédikt Tran. * #11666: Skip all hidden directories in ``CatalogRepository.pofiles``. Patch by Aryaz Eghbali. * #9686: html builder: Fix MathJax lazy loading when equations appear in titles. Patch by Bénédikt Tran. * #11483: singlehtml builder: Fix MathJax lazy loading when the index does not contain any math equations. Patch by Bénédikt Tran. * #11697: HTML Search: add 'noindex' meta robots tag. Patch by James Addison. * #11678: Fix a possible ``ZeroDivisionError`` in ``sphinx.ext.coverage``. Patch by Stephen Finucane. * #11756: LaTeX: build error with recent TeXLive due to missing ``substitutefont`` package (triggered if using ``fontenc`` with ``T2A`` option and document language is not a Cyrillic one). Patch by Jean-François B. * #11675: Fix rendering of progression bars in environments that do not support ANSI control sequences. Patch by Bénédikt Tran. * #11861: Whitelist more types with an incorrect ``__module__`` attribute. Patch by Adam Turner. * #11715: Apply ``tls_verify`` and ``tls_cacerts`` config to ``ImageDownloader``. Patch by Nick Touran. * Allow hyphens in group names for :rst:dir:`productionlist` cross-references. Patch by Adam Turner. * #11433: Added the :confval:`linkcheck_allow_unauthorized` configuration option. Set this option to ``False`` to report HTTP 401 (unauthorized) server responses as broken. Patch by James Addison. * #11868: linkcheck: added a distinct ``timeout`` reporting status code. This can be enabled by setting :confval:`linkcheck_report_timeouts_as_broken` to ``False``. Patch by James Addison. * #11869: Refresh the documentation for the ``linkcheck_timeout`` setting. Patch by James Addison. * #11874: Configure a default 30-second value for ``linkcheck_timeout``. Patch by James Addison. * #11886: Print the Jinja2 template path chain in ``TemplateNotFound`` exceptions. Patch by Colin Marquardt. * #11598: Do not use query components in URLs for assets in EPUB rendering. Patch by David Runge. * #11904: Support unary subtraction when parsing annotations. Patch by James Addison. * #11925: Blacklist the ``sphinxprettysearchresults`` extension; the functionality it provides was merged into Sphinx v2.0.0. Patch by James Addison. * #11917: Fix rendering of annotated inherited members for Python 3.9. Patch by Janet Carson. * #11935: C Domain: Fix namespace-pop context. Patch by Frank Dana. * #11923: Avoid zombie processes when parallel builds fail. Patch by Felix von Drigalski. * #11353: Support enumeration classes inheriting from mixin or data types. Patch by Bénédikt Tran. * #11962: Fix target resolution when using ``:paramtype:`` fields. Patch by Bénédikt Tran. * #11944: Use anchor in search preview. Patch by Will Lachance. * #12008: Fix case-sensitive lookup of ``std:label`` names in intersphinx inventory. Patch by Michael Goerz. * #11958: HTML Search: Fix partial matches overwriting full matches. Patch by William Lachance. * #11959: Fix multiple term matching when word appears in both title and document. Patch by Will Lachance. * #11474: Fix doctrees caching causing files not be rebuilt in some cases, e.g., when :confval:`numfig` is ``True``. Patch by Bénédikt Tran. * #11278: autodoc: Fix rendering of :class:`functools.singledispatchmethod` combined with :func:`@classmethod <classmethod>`. Patch by Bénédikt Tran. * #11894: Do not add checksums to css files if building using the htmlhelp builder. Patch by reduerK akiM. * #12052: Remove ``<script>`` and ``<style>`` tags from the content of search result summary snippets. Patch by James Addison. * #11578: HTML Search: Order non-main index entries after other results. Patch by Brad King. * #12147: autosummary: Fix a bug whereby the wrong file extension may be used, when multiple suffixes are specified in :confval:`source_suffix`. Patch by Sutou Kouhei. * #10786: improve the error message when a file to be copied (e.g., an asset) is removed during Sphinx execution. Patch by Bénédikt Tran. * #12040: HTML Search: Ensure that document titles that are partially-matched by the user search query are included in search results. Patch by James Addison. * #11970: 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``. Patch by Eric Norige. * #12271: Partially revert Docutils' r9562__ to fix EPUB files. Patch by Adam Turner. __ https://sourceforge.net/p/docutils/code/9562/ * #12253: Escape reserved path characters in the remote images post-transform download cache. Patch by James Addison and Adam Turner. Testing ------- * Reorganise tests into directories. Patch by Adam Turner. * Clean up global state in ``SphinxTestApp``. Patch by Adam Turner. * #11285: :func:`!pytest.mark.sphinx` and :class:`!sphinx.testing.util.SphinxTestApp` accept *warningiserror*, *keep_going* and *verbosity* as keyword arguments. Patch by Bénédikt Tran. * #11285: :class:`!sphinx.testing.util.SphinxTestApp` *status* and *warning* arguments are checked to be :class:`io.StringIO` objects (the public API incorrectly assumed this without checking it). Patch by Bénédikt Tran. * Report the result of ``test_run_epubcheck`` as ``skipped`` instead of ``success`` when either Java or ``epubcheck`` are not available. * Use dynamic allocation of unused port numbers for the test HTTP(S) servers. As a side-effect, this removes the need for test server lockfiles, meaning that any remaining ``tests/test-server.lock`` files can safely be deleted.
py-sphinx: update to 7.2.6.
Release 7.2.6 (released Sep 13, 2023)
=====================================
Bugs fixed
----------
* #11679: Add the :envvar:`!SPHINX_AUTODOC_RELOAD_MODULES` environment variable,
which if set reloads modules when using autodoc with ``TYPE_CHECKING = True``.
Patch by Matt Wozniski and Adam Turner.
* #11679: Use :py:func:`importlib.reload` to reload modules in autodoc.
Patch by Matt Wozniski and Adam Turner.
Release 7.2.5 (released Aug 30, 2023)
=====================================
Bugs fixed
----------
* #11645: Fix a regression preventing autodoc from importing modules within
packages that make use of ``if typing.TYPE_CHECKING:`` to guard circular
imports needed by type checkers.
Patch by Matt Wozniski.
* #11634: Fixed inheritance diagram relative link resolution
for sibling files in a subdirectory.
Patch by Albert Shih.
* #11659: Allow ``?config=...`` in :confval:`mathjax_path`.
* #11654: autodoc: Fail with a more descriptive error message
when an object claims to be an instance of ``type``,
but is not a class.
Patch by James Braza.
* 11620: Cease emitting :event:`source-read` events for files read via
the :dudir:`include` directive.
* 11620: Add a new :event:`include-read` for observing and transforming
the content of included files via the :dudir:`include` directive.
* #11627: Restore support for copyright lines of the form ``YYYY``
when ``SOURCE_DATE_EPOCH`` is set.
Release 7.2.4 (released Aug 28, 2023)
=====================================
Bugs fixed
----------
* #11618: Fix a regression in the MoveModuleTargets transform,
introduced in #10478 (#9662).
* #11649: linkcheck: Resolve hanging tests for timezones west of London
and incorrect conversion from UTC to offsets from the UNIX epoch.
Patch by Dmitry Shachnev and Adam Turner.
Release 7.2.3 (released Aug 23, 2023)
=====================================
Dependencies
------------
* #11576: Require sphinxcontrib-serializinghtml 1.1.9.
Bugs fixed
----------
* Fix regression in ``autodoc.Documenter.parse_name()``.
* Fix regression in JSON serialisation.
* #11543: autodoc: Support positional-only parameters in ``classmethod`` methods
when ``autodoc_preserve_defaults`` is ``True``.
* Restore support string methods on path objects.
This is deprecated and will be removed in Sphinx 8.
Use :py:func:`os.fspath` to convert :py:class:`~pathlib.Path` objects to strings,
or :py:class:`~pathlib.Path`'s methods to work with path objects.
Release 7.2.2 (released Aug 17, 2023)
=====================================
Bugs fixed
----------
* Fix the signature of the ``StateMachine.insert_input()`` patch,
for when calling with keyword arguments.
* Fixed membership testing (``in``) for the :py:class:`str` interface
of the asset classes (``_CascadingStyleSheet`` and ``_JavaScript``),
which several extensions relied upon.
* Fixed a type error in ``SingleFileHTMLBuilder._get_local_toctree``,
``includehidden`` may be passed as a string or a boolean.
* Fix ``:noindex:`` for ``PyModule`` and ``JSModule``.
Release 7.2.1 (released Aug 17, 2023)
=====================================
Bugs fixed
----------
* Restored the the :py:class:`str` interface of the asset classes
(``_CascadingStyleSheet`` and ``_JavaScript``), which several extensions relied upon.
This will be removed in Sphinx 9.
* Restored calls to ``Builder.add_{css,js}_file()``,
which several extensions relied upon.
* Restored the private API ``TocTree.get_toctree_ancestors()``,
which several extensions relied upon.
Release 7.2.0 (released Aug 17, 2023)
=====================================
Dependencies
------------
* #11511: Drop Python 3.8 support.
* #11576: Require Pygments 2.14 or later.
Deprecated
----------
* #11512: Deprecate ``sphinx.util.md5`` and ``sphinx.util.sha1``.
Use ``hashlib`` instead.
* #11526: Deprecate ``sphinx.testing.path``.
Use ``os.path`` or ``pathlib`` instead.
* #11528: Deprecate ``sphinx.util.split_index_msg`` and ``sphinx.util.split_into``.
Use ``sphinx.util.index_entries.split_index_msg`` instead.
* Deprecate ``sphinx.builders.html.Stylesheet``
and ``sphinx.builders.html.Javascript``.
Use ``sphinx.application.Sphinx.add_css_file()``
and ``sphinx.application.Sphinx.add_js_file()`` instead.
* #11582: Deprecate ``sphinx.builders.html.StandaloneHTMLBuilder.css_files`` and
``sphinx.builders.html.StandaloneHTMLBuilder.script_files``.
Use ``sphinx.application.Sphinx.add_css_file()``
and ``sphinx.application.Sphinx.add_js_file()`` instead.
* #11459: Deprecate ``sphinx.ext.autodoc.preserve_defaults.get_function_def()``.
Patch by Bénédikt Tran.
Features added
--------------
* #11526: Support ``os.PathLike`` types and ``pathlib.Path`` objects
in many more places.
* #5474: coverage: Print summary statistics tables.
Patch by Jorge Leitao.
* #6319: viewcode: Add :confval:`viewcode_line_numbers` to control
whether line numbers are added to rendered source code.
Patch by Ben Krikler.
* #9662: Add the ``:no-typesetting:`` option to suppress textual output
and only create a linkable anchor.
Patch by Latosha Maltba.
* #11221: C++: Support domain objects in the table of contents.
Patch by Rouslan Korneychuk.
* #10938: doctest: Add :confval:`doctest_show_successes` option.
Patch by Trey Hunner.
* #11533: Add ``:no-index:``, ``:no-index-entry:``, and ``:no-contents-entry:``.
* #11572: Improve ``debug`` logging of reasons why files are detected as out of
date.
Patch by Eric Larson.
* #10678: Emit :event:`source-read` events for files read via
the :dudir:`include` directive.
Patch by Halldor Fannar.
* #11570: Use short names when using :pep:`585` built-in generics.
Patch by Riccardo Mori.
* #11300: Improve ``SigElementFallbackTransform`` fallback logic and signature
text elements nodes. See :doc:`the documentation </extdev/nodes>` for more
details.
Patch by Bénédikt Tran.
* Allow running Sphinx with ``python -m sphinx build ...``.
Bugs fixed
----------
* #11077: graphviz: Fix relative links from within the graph.
Patch by Ralf Grubenmann.
* #11529: Line Block in LaTeX builder outputs spurious empty token.
Patch by Adrian Vollmer.
* #11196: autosummary: Summary line extraction failed with "e.g."
* #10614: Fixed a number of bugs in inheritance diagrams that resulted in
missing or broken links.
Patch by Albert Shih.
* #9428: Exclude substitution definitions when running the ``gettext`` builder.
Patch by Alvin Wong.
* #10795: Raise a descriptive error if ``graphviz_dot`` is falsy.
* #11546: Translated nodes identical to their original text are now marked
with the ``translated=True`` attribute.
* #10049: html: Change "Permalink" to "Link" for title text in link anchors.
* #4225: Relax Pygments parsing on lexing failures.
* #11246: Allow inline links in the first line of a docstring and one-line
type comments ``#: :meta ...:`` when using :mod:`sphinx.ext.napoleon`.
Patch by Bénédikt Tran.
* #10930: Highlight all search terms on the search results page.
Patch by Dmitry Shachnev.
* #11473: Type annotations containing :py:data:`~typing.Literal` enumeration
values now render correctly.
Patch by Bénédikt Tran.
* #11591: Fix support for C coverage in ``sphinx.ext.coverage`` extension.
Patch by Stephen Finucane.
* #11594: HTML Theme: Enhancements to horizontal scrolling on smaller
devices in the ``agogo`` theme.
Patch by Lukas Engelter.
* #11459: Fix support for async and lambda functions in
``sphinx.ext.autodoc.preserve_defaults``.
Patch by Bénédikt Tran.
Testing
-------
* #11577: pytest: Fail tests on "XPASS".
* #11577: pytest: Use "importlib" import mode.
* #11577: pytest: Set PYTHONWARNINGS=error.
* #11577: pytest: Set strict config and strict markers.
python/wheel.mk: simplify a lot, and switch to 'installer' for installation This follows the recommended bootstrap method (flit_core, build, installer). However, installer installs different files than pip, so update PLISTs for all packages using wheel.mk and bump their PKGREVISIONs.
py-sphinx: updated to 7.1.2
Release 7.1.2 (released Aug 02, 2023)
=====================================
Bugs fixed
----------
* linkcheck: Properly respect :confval:`linkcheck_anchors`
and do not spuriously report failures to validate anchors.
Patch by James Addison.
Release 7.1.1 (released Jul 27, 2023)
=====================================
Bugs fixed
----------
* Fix ``SOURCE_DATE_EPOCH`` in multi-line copyright footer.
Patch by Bénédikt Tran.
Release 7.1.0 (released Jul 24, 2023)
=====================================
Incompatible changes
--------------------
* Releases are no longer signed, given the `change in PyPI policy`_.
.. _change in PyPI policy: https://blog.pypi.org/posts/2023-05-23-removing-pgp/
Deprecated
----------
* Emit warnings on using a deprecated Python-specific index entry type
(namely, ``module``, ``keyword``, ``operator``, ``object``, ``exception``,
``statement``, and ``builtin``) in the :rst:dir:`index` directive, and
set the removal version to Sphinx 9. Patch by Adam Turner.
Features added
--------------
* Add a checksum to JavaScript and CSS asset URIs included within
generated HTML, using the CRC32 algorithm.
* :meth:`~sphinx.application.Sphinx.require_sphinx` now allows the version
requirement to be specified as ``(major, minor)``.
* Allow configuring a line-length limit for object signatures, via
:confval:`maximum_signature_line_length` and the domain-specific variants.
If the length of the signature (in characters) is greater than the configured
limit, each parameter in the signature will be split to its own logical line.
This behaviour may also be controlled by options on object description
directives, for example :rst:dir:`py:function:single-line-parameter-list`.
Patch by Thomas Louf, Adam Turner, and Jean-François B.
* Support for multiline copyright statements in the footer block.
Patch by Stefanie Molin
* ``sphinx.util.display.status_iterator`` now clears the current line
with ANSI control codes, rather than overprinting with space characters.
* linkcheck: Treat SSL failures as broken links.
Patch by James Addison.
* Keep the ``translated`` attribute on translated nodes.
* Improve the traceback displayed when using :option:`sphinx-build -T`
in parallel builds. Patch by Bénédikt Tran
* linkcheck: Use session-basd HTTP requests.
* Add support for the :rst:dir:`py:class` and :rst:dir:`py:function`
directives for PEP 695 (generic classes and functions declarations) and
PEP 696 (default type parameters). Multi-line support is enabled
for type parameters list and can be locally controlled on object description
directives, e.g., :rst:dir:`py:function:single-line-type-parameter-list`.
Patch by Bénédikt Tran.
* linkcheck: Allow HTML anchors to be ignored on a per-URL basis
via :confval:`linkcheck_anchors_ignore_for_url` while
still checking the validity of the page itself.
Patch by Bénédikt Tran
* Add translation progress statistics and inspection support,
via a new substitution (``|translation progress|``) and a new
configuration variable (:confval:`translation_progress_classes`).
These enable determining the percentage of translated elements within
a document, and the remaining translated and untranslated elements.
Bugs fixed
----------
* Restored the ``footnote-reference`` class that has been removed in
the latest (unreleased) version of Docutils.
* Use :rfc:`8081` font file MIME types in the EPUB builder.
Using the correct MIME type will prevent warnings from ``epubcheck``
and will generate a valid EPUB.
* Use microsecond-resolution timestamps for outdated file detection
in ``BuildEnvironment.get_outdated_files``.
* Top-level headings starting with a reStructuredText role
now render properly when :confval:`rst_prolog` is set.
Previously, a file starting with the below would have
improperly rendered due to where the prologue text
was inserted into the document.
.. code:: rst
:mod:`lobster` -- The lobster module
====================================
...
Patch by Bénédikt Tran.
* Fix a ``MemoryError`` in ``sphinx.ext.intersphinx`` when using ``None``
or ``typing.*`` as inline type references. Patch by Bénédikt Tran (picnixz)
Testing
-------
* Always delete ``docutils.conf`` in test directories when running
``SphinxTestApp.cleanup()``.
py-sphinx: updated to 7.0.0 Release 7.0.0 (released Apr 29, 2023) Incompatible changes * Remove long-deprecated aliases for MecabSplitter and DefaultSplitter in sphinx.search.ja. * Remove deprecated make_old_id functions in domain object description classes. * Remove the Setuptools integration (build_sphinx hook in setup.py). * Remove deprecated sphinx.ext.napoleon.iterators module. * Remove support for the jsdump format in sphinx.search. * Make locale a required argument to sphinx.util.i18n.format_date(). * Remove deprecated sphinx.util.stemmer module. * Remove deprecated sphinx.pycode.ast.parse() function. * Remove deprecated sphinx.io.read_doc() function. * Removed deprecated sphinx.util.get_matching_files() function. * Remove deprecated sphinx.util.docutils.is_html5_writer_available() function. * Make the env argument to Builder subclasses required. * autosummary: Always emit grouped import exceptions. * Remove deprecated style key for HTML templates. * Remove deprecated sphinx.writers.latex.LaTeXTranslator.docclasses attribute. * Remove deprecated sphinx.builders.html.html5_ready and sphinx.builders.html.HTMLTranslator attributes. * Remove support for HTML 4 output.
py-sphinx: updated to 5.3.0 Release 5.3.0 (released Oct 16, 2022) ===================================== Features added -------------- * LaTeX: add :confval:`latex_table_style` and support the ``'booktabs'``, ``'borderless'``, and ``'colorrows'`` styles. * One can cross-reference including an option value like ``:option:`--module=foobar```, ``:option:`--module[=foobar]``` or ``:option:`--module foobar```. Patch by Martin Liska. * autosectionlabel: Record the generated section label to the debug log. * Correctly URI-escape image filenames. * domains: Allow sections in all the content of all object description directives (e.g. :rst:dir:`py:function`). Patch by Adam Turner Release 5.2.3 (released Sep 30, 2022) ===================================== * Fix base64 image embedding in ``sphinx.ext.imgmath`` * Add ``:nocontentsentry:`` flag and global domain table of contents entry control option. Patch by Adam Turner Release 5.2.2 (released Sep 27, 2022) ===================================== * Restore link targets for autodoc modules to the top of content. Patch by Dominic Davis-Foster. Release 5.2.1 (released Sep 25, 2022) ===================================== Bugs fixed ---------- * Always normalise the ``pycon3`` lexer to ``pycon``. * Fix using ``sphinx.ext.autosummary`` with modules containing titles in the module-level docstring. Release 5.2.0.post0 (released Sep 24, 2022) =========================================== * Recreated source tarballs for Debian maintainers. Release 5.2.0 (released Sep 24, 2022) ===================================== Dependencies ------------ * Sphinx now uses declarative metadata with ``pyproject.toml`` to create packages, using PyPA's ``flit`` project as a build backend. Patch by Adam Turner. Deprecated ---------- * Support for HTML 4 output. Patch by Adam Turner. Features added -------------- * napoleon: Add support for docstring types using 'of', like ``type of type``. Example: ``tuple of int``. * C++, support requires clauses not just between the template parameter lists and the declaration. * linkcheck: Check the source URL of raw directives that use the ``url`` option. * Allow :rst:role:`ref` role to be used with definitions and fields. * HTML Search: Increase priority for full title and subtitle matches in search results * HTML Search: Save search result score to the HTML element for debugging * Make toctree accept 'genindex', 'modindex' and 'search' docnames * Add domain objects to the table of contents. Patch by Adam Turner * HTML Search: Include explicit :rst:dir:`index` directive index entries in the search index and search results. Patch by Adam Turner * imgmath: Allow embedding images in HTML as base64 * HTML Search: Use browser localstorage for highlight control, stop storing highlight parameters in URL query strings. Patch by Adam Turner. Bugs fixed ---------- * LaTeX: 5.1.0 has made the 'sphinxsetup' ``verbatimwithframe=false`` become without effect. * C++, ensure consistent non-specialization template argument representation. * C++, fix parsing of certain non-type template parameter packs. * Revert 10520: "Fix" use of sidebar classes in ``agogo.css_t`` Release 5.1.1 (released Jul 26, 2022) ===================================== Bugs fixed ---------- * Fix ValueError in the new ``deque`` based ``sphinx.ext.napolean`` iterator implementation. * Restore compatability with third-party builders. Release 5.1.0 (released Jul 24, 2022) ===================================== Dependencies ------------ * Support `Docutils 0.19`_. Patch by Adam Turner. Deprecated ---------- * Deprecated ``sphinx.util.stemmer`` in favour of ``snowballstemmer``. Patch by Adam Turner. * Deprecated ``sphinx.ext.napoleon.iterators``. Features added -------------- * html theme: Allow specifying multiple CSS files through the ``stylesheet`` setting in ``theme.conf`` or by setting ``html_style`` to an iterable of strings. * std domain: Add support for emphasising placeholders in :rst:dir:`option` directives through a new :confval:`option_emphasise_placeholders` configuration option. * std domain: Use the repr of some variables when displaying warnings, making whitespace issues easier to identify. * quickstart: Reduce content in the generated ``conf.py`` file. Patch by Pradyun Gedam. * LaTeX: CSS-named-alike additional :ref:`'sphinxsetup' <latexsphinxsetup>` keys allow to configure four separate border-widths, four paddings, four corner radii, a shadow (possibly inset), colours for border, background, shadow for each of the code-block, topic, attention, caution, danger, error and warning directives. * LaTeX: Explain non-standard encoding in LatinRules.xdy * HTML Theme: Wrap consecutive footnotes in an ``<aside>`` element when using Docutils 0.18 or later, to allow for easier styling. This matches the behaviour introduced in Docutils 0.19. Patch by Adam Turner. * config: Add ``include_patterns`` as the opposite of ``exclude_patterns``. Patch by Adam Turner. Bugs fixed ---------- * HTML Theme: field term colons are doubled if using Docutils 0.18+ * Build failure if Docutils version is 0.18 (not 0.18.1) due to missing ``Node.findall()`` * LaTeX: build error if highlighting inline code role in figure caption * Make -P (pdb) option work better with exceptions triggered from events * py domain: Fix spurious whitespace in unparsing various operators (``+``, ``-``, ``~``, and ``**``). Patch by Adam Turner. * logging: Always show node source locations as absolute paths. * HTML Search: HTML tags are displayed as a part of object name * HTML Search: search snipets should not be folded * HTML Search: Minor errors are emitted on fetching search snipets * HTML Search: The markers for header links are shown in the search result * HTML Theme: Fix use of sidebar classes in ``agogo.css_t``. * HTML Theme: Fix inclusion of hidden toctrees in the agogo theme. * HTML Theme: Fix enable_search_shortcuts does not work * LaTeX: Text can fall out of code-block at end of page and leave artifact on next page * LaTeX: user injected ``\color`` commands in topic or admonition boxes may cause color leaks in PDF due to upstream `framed.sty <https://ctan.org/pkg/framed>`_ bug * LaTeX: framed coloured boxes in highlighted code (e.g. highlighted diffs using Pygments style ``'manni'``) inherit thickness of code-block frame * LaTeX: Only one ``\label`` is generated for ``desc_signature`` node even if it has multiple node IDs * i18n: UnboundLocalError is raised on translating raw directive * py domain: Fix warning for duplicate Python references when using ``:any:`` and autodoc. * HTML Search: fix minor summary issues.
py-sphinx: updated to 4.2.0
Release 4.2.0 (released Sep 12, 2021)
=====================================
Features added
--------------
* autodoc: Support class properties
* autodoc: Emit a warning if target is a mocked object
* autodoc: Allow to refer NewType instances with module name in Python
3.10 or above
* html theme: Expose the version of Sphinx in the form of tuple as a
template variable ``sphinx_version_tuple``
* manpage: Suppress the title of man page if description is empty
* py domain: ``:py:property:`` directive supports ``:classmethod:``
option to describe the class property
* test: SphinxTestApp can take ``builddir`` as an argument
* C and C++, support more fundamental types, including GNU extensions.
Bugs fixed
----------
* apidoc: apidoc does not generate a module definition for implicit
namespace package
* autodoc: generate incorrect reference to the parent class if the target
class inherites the class having ``_name`` attribute
* autodoc: Some objects under ``typing`` module are not displayed
well with the HEAD of 3.10
* autodoc: typehint for cached_property is not shown
* autodoc: AttributeError is raised on failed resolving typehints
* autodoc: autodoc_docstring_signature does not effect to ``__init__()``
and ``__new__()``
* autodoc: PEP 585 style typehints having arguments (ex. ``list[int]``)
are not displayed well
* autosummary: some warnings contain non-existing filenames
* autosummary: summarise overlined sectioned headings correctly
* autosummary: Type annotations which contain commas in autosummary table
are not removed completely
* c domain: some warnings contain non-existing filenames
* cpp domain: some warnings contain non-existing filenames
* html search: abbreation marks are inserted to the search result if
failed to fetch the content of the page
* html search: The JS requirement warning is shown if browser is slow
* html theme: CSS and JS files added by theme were loaded twice
* py domain: ``:type:`` option for :rst:dir:`py:property` directive does
not create a hyperlink
* py domain: Literal typehint was converted to a cross reference
* comment: C++, fix parsing of defaulted function parameters that are
function pointers.
* smartquotes: don't adjust typography for text with
language-highlighted ``:code:`` role.
* sphinx-build: crashed with the HEAD of Python 3.10
Release 4.1.2 (released Jul 27, 2021)
=====================================
Incompatible changes
--------------------
* linkcheck: Disable checking automatically generated anchors on
github.com (ex. anchors in reST/Markdown documents)
Bugs fixed
----------
* autodoc: Custom types using ``typing.NewType`` are not displayed well
with the HEAD of 3.10
* autodoc: Some objects under ``typing`` module are not displayed well
with the HEAD of 3.10
* autodoc: crashed if ``autodoc_class_signature = "separated"``
* html search: html_copy_source can't control the search summaries
* linkcheck: Failed to check anchors in github.com
Release 4.1.1 (released Jul 15, 2021)
=====================================
Dependencies
------------
* sphinxcontrib-htmlhelp-2.0.0 or above
* sphinxcontrib-serializinghtml-1.1.5 or above
Bugs fixed
----------
* 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
--------------
* autodoc: Add ``class-doc-from`` option to :rst:dir:`autoclass`
directive to control the content of the specific class like
:confval:`autoclass_content`
* autodoc: :confval:`autodoc_type_aliases` now supports dotted name. It
allows you to define an alias for a class with module name like
``foo.bar.BazClass``
* autodoc: Special member is not documented in the module
* autodoc: The arguments of ``typing.Literal`` are wrongly rendered
* autodoc: :confval:`autodoc_typehints` allows ``'both'`` setting to
allow typehints to be included both in the signature and description
* autodoc: Add :confval:`autodoc_class_signature` to separate the class
entry and the definition of ``__init__()`` method
* autodoc: Support variable comment for alias classes
* autodoc: Add :event:`autodoc-process-bases` to modify the base classes
of the class definitions
* autodoc: Render enum values for the default argument value better
* autodoc: ``autodoc_typehints='none'`` now erases typehints for
variables, attributes and properties
* autosummary: Support instance attributes for classes
* html: Add "heading" role to the toctree items
* html: Add span tag to the return typehint of method/function
* html search: Show search summaries when html_copy_source = False
* html search: Prevent corrections and completions in search field
* html theme: Eliminate prompt characters of code-block from copyable
text
* i18n: Emit a debug message if message catalog file not found under
:confval:`locale_dirs`
* LaTeX: Add xeCJKVerbAddon to default fvset config for Chinese documents
* linkcheck: Support checking anchors on github.com
* linkcheck: Add a new event :event:`linkcheck-process-uri` to modify
URIs before checking hyperlinks
* linkcheck: Add :confval:`linkcheck_allowed_redirects` to mark
hyperlinks that are redirected to expected URLs as "working"
* py domain: Support union types using ``|`` in info-field-list
* py domain: :confval:`python_use_unqualified_type_names` supports type
field in info-field-list
* Optimize the parallel build
* Add :confval:`nitpick_ignore_regex` to ignore nitpicky warnings using
regular expressions
* 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(<constant expression>)`` 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.
* LaTeX: support containers in LaTeX output
Bugs fixed
----------
* autodoc: stacked singledispatches are wrongly rendered
* autodoc: a docsting having metadata only should be treated as
undocumented
* autodoc: typehints for overloaded functions and methods are inaccurate
* autodoc: The inherited method not having docstring is wrongly parsed
* autodoc: autoattribute directive failed to generate document for an
attribute not having any comment
* autodoc: single element tuple on the default argument value is wrongly
rendered
* autodoc: AttributeError is raised on processing a subclass of Tuple[()]
* autodoc: TypeError is raised on processing dict-like object (not a
class) via autoclass directive
* html: Pushing left key causes visiting the next page at the first page
* html: URL for html_favicon and html_log does not work
* html theme : pyramid theme generates incorrect logo links
* manpage: The name of manpage directory that is generated by
:confval:`man_make_section_directory` is not correct
* manpage: Fix font isn't reset after keyword at the top of samp role
* Linkcheck reports broken link when remote server closes the connection
on HEAD request
* py domain: "exceptions" module is not displayed
* py domain: a Callable annotation with no parameters
(e.g. ``Callable[[], None])`` will be rendered with a bracket missing
(``Callable[], None]``)
* quickstart: Make sphinx-quickstart exit when conf.py already exists
* xml: XML Builder ignores custom visitors
* ``:param:`` and ``:type:`` fields does not support a type containing
whitespace (ex. ``Dict[str, str]``)
* 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``.
* C, add :confval:`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
----------
* changeset domain: :rst:dir:`versionchanged` with contents being a list
will cause error during pdf build
* LaTeX: complex table with merged cells broken since 4.0
* LaTeX: backslash may cause Improper discretionary list pdf build error
with Japanese engines
* C, remove special macro names from the keyword list.
See also :confval:`c_extra_keywords`.
* KeyError is raised on PropagateDescDomain transform
Release 4.0.2 (released May 20, 2021)
=====================================
Dependencies
------------
* Support jinja2-3.0
Incompatible changes
--------------------
* Update Underscore.js to 1.13.1
* manpage: Stop creating a section directory on build manpage by default
(see :confval:`man_make_section_directory`)
Bugs fixed
----------
* viewcode: crashed if non importable modules found on parallel build
* 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
----------
* autodoc: crashed when ValueError is raised on generating signature
from a property of the class
* autosummary: warning is emitted if list value is set to
autosummary_generate
* html search: tags for search result are broken
* i18n: Babel emits errors when running compile_catalog
* py domain: The :canonical: option causes "more than one target for
cross-reference" warning
* 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
* autodoc: info-field-list is generated into the class description when
``autodoc_typehints='description'`` and ``autoclass_content='class'`` set
* 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 overridden in the concrete classes
* py domain: The structure of python objects is changed. A boolean value
is added to indicate that the python object is canonical one
* 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 :mod:`sphinx.ext.mathjax`.
* i18n: The msgid for alt text of image is changed
* napoleon: :confval:`napoleon_use_param` also affect "other parameters"
section
* manpage: Make a section directory on build manpage by default (see
:confval:`man_make_section_directory`)
* html: Change the default setting of
:confval:`html_codeblock_linenos_style` to ``'inline'``
* html search: search results are wrapped with ``<p>`` instead of
``<div>``
* 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
* html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
* LaTeX: uplatex becomes a default setting of latex_engine for Japanese
documents
* py domain: ``:var:``, ``:cvar:`` and ``:ivar:`` fields do not create
cross-references
* The ``align`` attribute of ``figure`` and ``table`` nodes becomes
``None`` by default instead of ``'default'``
* LaTeX refactoring: split sphinx.sty into multiple files and rename
some auxiliary files created in ``latex`` build output repertory
* Use explicit title instead of <no title>
* The :file: option for csv-table directive now recognizes an absolute
path as a relative path from source directory
4.0.0b2
* Change the CSS classes on :rst:role:`cpp:expr` and
:rst:role:`cpp:texpr`.
Deprecated
----------
* :confval:`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
* autodoc: Support ``bound`` argument for TypeVar
* autodoc: Support typehints for properties
* 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
* autodoc: Add :confval:`autodoc_typehints_description_target` to control
the behavior of ``autodoc_typehints=description``
* autodoc: :confval:`autodoc_docstring_signature` will continue to look
for multiple signature lines without backslash character
* autosummary: Enable :confval:`autosummary_generate` by default
* extlinks: Allow %s in link caption string
* py domain: Add ``:canonical:`` option to python directives to describe
the location where the object is defined
* py domain: Add :confval:`python_use_unqualified_type_names` to suppress
the module name of the python reference if it can be resolved (experimental)
* py domain: Add :rst:dir:`py:property` directive to describe a property
* i18n: The alt text for image is translated by default (without
:confval:`gettext_additional_targets` setting)
* html: :confval:`html_favicon` and :confval:`html_logo` now accept URL
for the image
* html search: Support searching for 2characters word
* html theme: Allow to inherite the search page
* imgconverter: Show the error of the command availability check
* Add debug logs for change detection of sources and templates
* Emit a warning if toctree contains duplicated entries
* ``master_doc`` is now renamed to :confval:`root_doc`
* C++, add support for the C++20 spaceship operator, ``<=>``.
* 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
* autodoc: Super class having ``Any`` arguments causes nit-picky warning
* autodoc: TypeError is raised on processing broken metaclass
* autodoc: metadata of GenericAlias is not rendered as a reference in
py37+
* html: copy-range protection for doctests doesn't work in Safari
* LaTeX: imgconverter: conversion runs even if not needed
* py domain: Ellipsis in info-field-list causes nit-picky warning
* py domain: duplicated warning is emitted when both canonical and its
alias objects are defined on the document
* More CSS classes on domain descriptions, see :ref:`nodes` for details.
* mathjax: Rename :confval:`mathjax_config` to
:confval:`mathjax2_config` and add :confval:`mathjax3_config`
Bugs fixed
----------
4.0.0b1
* autodoc: Raises a warning if function has wrong __globals__ value
* autodoc: a TypeVar imported from other module is not resolved (in
Python 3.7 or above)
* autodoc: Failed to resolve types.TracebackType type annotation
* html: html_add_permalinks=None and html_add_permalinks="" are ignored
* html search: Paragraphs in search results are not identified as ``<p>``
* html theme: The translation of sphinx_rtd_theme does not work
* Emit a warning if a unknown domain is given for directive or role (ex.
``:unknown:doc:``)
* LaTeX: No wrapping for ``cpp:enumerator``
* LaTeX: backticks in code-blocks trigger latexpdf build warning (and font
change) with late TeXLive 2019
* LaTeX: Figures with no size defined get overscaled (compared to images
with size explicitly set in pixels) (fixed for ``'pdflatex'/'lualatex'`` only)
* LaTeX: The depth of bookmarks panel in PDF is not enough for navigation
* LaTeX: the fix to two minor Pygments LaTeXFormatter output issues ignore
Pygments style
* LaTeX: 3.5.0 ``verbatimmaxunderfull`` setting does not work as
expected
* LaTeX: missing line break in ``\pysigline``
* LaTeX: legacy ``\pysiglinewithargsret`` does not compute correctly
available horizontal space and should use a ragged right style
* LaTeX: "release" value with underscore leads to invalid LaTeX
* C++: remove the longest matching prefix in
:confval:`cpp_index_common_prefix` instead of the first that matches.
* C, properly reject function declarations when a keyword is used
as parameter name.
* viewcode: Failed to create back-links on parallel build
* 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
* html: Failed to add CSS files to the specific page
py-sphinx: updated to 3.5.3
Release 3.5.3 (released Mar 20, 2021)
=====================================
Features added
--------------
* using UNIX path separator in image directive confuses Sphinx on Windows
Release 3.5.2 (released Mar 06, 2021)
=====================================
Bugs fixed
----------
* i18n: Crashed by broken translation messages in ES, EL and HR
* LaTeX: A custom LaTeX builder fails with unknown node error
* Exceptions raised in a Directive cause parallel builds to hang
Release 3.5.1 (released Feb 16, 2021)
=====================================
Bugs fixed
----------
* autodoc: AttributeError is raised on assigning __annotations__ on
read-only class
* html: minified js stemmers not included in the distributed package
* html: AttributeError is raised if CSS/JS files are installed via
:confval:`html_context`
* 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
* html: The config variable ``html_add_permalinks`` is replaced by
:confval:`html_permalinks` and :confval:`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
--------------
* autodoc: autodata and autoattribute directives does not show right-hand
value of the variable if docstring contains ``:meta hide-value:`` in
info-field-list
* autodoc: Default values of overloaded functions are taken from actual
implementation if they're ellipsis
* autodoc: Support type union operator (PEP-604) in Python 3.10 or above
* autodoc: Allow to extend :confval:`autodoc_default_options` via
directive options
* html: kbd role generates customizable HTML tags for compound keys
* html: Allow to change the order of JS/CSS via ``priority`` parameter
for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()`
* 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
:event:`html-page-context` event
* html: Allow to use HTML permalink texts via
:confval:`html_permalinks_icon`
* html: Add permalink icons to glossary terms
* html search: performance issue with massive lists
* html search: Update JavaScript stemmer code to the latest version of
Snowball (v2.1.0)
* i18n: Allow to translate heading syntax in MyST-Parser
* imgconverter: Skip availability check if builder supports the image
type
* napoleon: Allow to change the style of custom sections using
:confval:`napoleon_custom_styles`
* napoleon: Type definitions in Google style docstrings are rendered as
references when :confval:`napoleon_preprocess_types` enabled
* mathjax: Include mathjax.js only on the document using equations
* py domain: Support type union operator (PEP-604)
* std domain: cross-reference for a rubric having inline item is broken
* std domain: Optimize case-insensitive match of term
* viewcode: Support incremental build
* Add :confval:`project_copyright` as an alias of :confval:`copyright`
* Now :confval:`highlight_language` supports multiple languages
* :rst:dir:`code-block` and :rst:dir:`literalinclude` supports automatic
dedent via no-argument ``:dedent:`` option
* C++, also hyperlink operator overloads in expressions and alias declarations.
* Allow production lists to refer to tokens from other production groups
* Show what extension (or module) caused it on errors on event handler
* C++: add ``maxdepth`` option to :rst:dir:`cpp:alias` to insert nested
declarations.
* C, add ``noroot`` option to :rst:dir:`c:alias` to render only nested
declarations.
* C++, add ``noroot`` option to :rst:dir:`cpp:alias` to render only nested
declarations.
Bugs fixed
----------
* apidoc: namespace module file is not generated if no submodules there
* autodoc: inherited-members doesn't work for instance attributes on super
class
* autodoc: ``:meta public:`` does not effect to variables
* autodoc: empty __all__ attribute is ignored
* autodoc: Failed to resolve struct.Struct type annotation
* autodoc: All variable comments in the module are ignored if the module
contains invalid type comments
* autodoc: Default values for overloaded functions are rendered as string
* autodoc: crashes when mocked decorator takes arguments
* autodoc: Uninitialized attributes in superclass are recognized as
undocumented
* autodoc: Failed to generate document if target module contains an
object that raises an exception on ``hasattr()``
* autosummary: mocked modules are documented as empty page when using
:recursive: option
* graphviz: Image node is not rendered if graph file is in subdirectory
* html: kbd role produces incorrect HTML when compound-key separators (-,
+ or ^) are used as keystrokes
* html: A type warning for html_use_opensearch is shown twice
* html: kbd role with "Caps Lock" rendered incorrectly
* html search: fix searching for terms containing + (Requires a custom
search language that does not split on +)
* html theme: Could not override globaltoc_maxdepth in theme.conf
* html: consecutive spaces are displayed as single space
* i18n: crashes with KeyError when translation message adds a new auto
footnote reference
* linkcheck: Fix race condition that could lead to checking the
availability of the same URL twice
* linkcheck: The docname for each hyperlink is not displayed
* sphinx-quickstart: questionare got Mojibake if libreadline unavailable
* texinfo: image files on the different directory with document are not
copied
* todo: Cross references in todolist get broken
* viewcode: module pages are generated for epub on incremental build
* viewcode: anchors are generated in incremental build after singlehtml
* viewcode: highlighted code is generated even if not referenced
* :confval:`highlight_options` is not working
* C, fix intersphinx lookup types for names in declarations.
* C, C++: in general fix intersphinx and role lookup types.
* :confval:`html_last_updated_fmt` does not support UTC offset (%z)
* :confval:`html_last_updated_fmt` generates wrong time zone for %Z
* ``download`` role creates duplicated copies when relative path is
specified
* (fifth item): LaTeX: footnotes from captions are not clickable,
and for manually numbered footnotes only first one with same number is
an hyperlink
* LaTeX with French babel and memoir crash: "Illegal parameter number
in definition of ``\FNH@prefntext``"
* LaTeX (docs): A potential display bug with the LaTeX generation step
in Sphinx (how to generate one-column index)
* LaTeX: Directive :rst:dir:`hlist` not implemented in LaTeX
* LaTeX: The :rst:role:`index` role and the glossary generate duplicate
entries in the LaTeX index (if both used for same term)
* LaTeX: wrong internal links in pdf to captioned code-blocks when
:confval:`numfig` is not True
* LaTeX: some indexed terms are ignored when using xelatex engine
(or pdflatex and :confval:`latex_use_xindy` set to True) with memoir class
* LaTeX: URLs as footnotes fail to show in PDF if originating from
inside function type signatures
* LaTeX: long words in narrow columns may not be hyphenated
* LaTeX: ``\titleformat`` last argument in sphinx.sty should be
bracketed, not braced (and is anyhow not needed)
* LaTex: code-block printed out of margin (see the opt-in LaTeX syntax
boolean :ref:`verbatimforcewraps <latexsphinxsetupforcewraps>` for use via
the :ref:`'sphinxsetup' <latexsphinxsetup>` key of ``latex_elements``)
* LaTeX: Remove substitution_reference nodes from doctree only on LaTeX
builds
* LaTeX: Restructure the index nodes inside title nodes only on LaTeX
builds
* LaTeX: potentially critical low level TeX coding mistake has gone
unnoticed so far
* C, :rst:dir:`c:alias` skip symbols without explicit declarations
instead of crashing.
* C, :rst:dir:`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
----------
* 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
----------
* autodoc: Classes that inherit mocked class are not documented
* autodoc: The ``autodoc-process-docstring`` event is emitted to the
non-datadescriptors unexpectedly
* autodoc: AttributeError is raised on non-class object is passed to
autoclass directive
Release 3.4.1 (released Dec 25, 2020)
=====================================
Bugs fixed
----------
* autodoc: AttributeError is raised when using forward-reference type
annotations
* autodoc: TypeError is raised on checking slots attribute
* autodoc: Instance attributes are incorrectly added to Parent class
* autodoc: The ``autodoc-process-docstring`` event is emitted to the
alias classes unexpectedly
* autodoc: Unnecessary object comparision via ``__eq__`` method
* linkcheck: Fix PriorityQueue crash when link tuples are not
comparable
Release 3.4.0 (released Dec 20, 2020)
=====================================
Incompatible changes
--------------------
* 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
--------------
* autodoc: Allow to determine whether a member not included in
``__all__`` attribute of the module should be documented or not via
:event:`autodoc-skip-member` event
* 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.
* autodoc: Add ``:no-value:`` option to :rst:dir:`autoattribute` and
:rst:dir:`autodata` directive to suppress the default value of the variable
* autodoc: Support custom types defined by typing.NewType
* napoleon: Add :confval:`napoleon_attr_annotations` to merge type hints
on source code automatically if any type is specified in docstring
* napoleon: Support numpydoc's "Receives" section
* Add a new event :event:`warn-missing-reference` to custom warning
messages when failed to resolve a cross-reference
* Emit a detailed warning when failed to resolve a ``:ref:`` reference
* linkcheck: The builder now handles rate limits. See
:confval:`linkcheck_retry_on_rate_limit` for details.
Bugs fixed
----------
* autodoc: autodoc does not respect __signature__ of the class
* autodoc: the location of the warning is incorrect for inherited method
* autodoc: the signature of class constructor is incorrect if the class
is decorated
* autodoc: :confval:`autodoc_type_aliases` does not effect to variables
and attributes
* autodoc: autodata directive can't create document for PEP-526 based
type annotated variables
* autodoc: autoattribute directive can't create document for PEP-526
based uninitalized variables
* autodoc: autoattribute could not create document for __slots__
attributes
* autodoc: autoattribute could not create document for a GenericAlias as
class attributes correctly
* autodoc: autoattribute could not create document for a commented
attribute in alias class
* autodoc: autodoc_type_aliases doesn't work when autodoc_typehints is
set to "description"
* autodoc: autodoc_type_aliases doesn't work for the type annotation to
instance attributes
* autodoc: autodata and autoattribute directives do not display type
information of TypeVars
* autodoc: references to builtins not working in class aliases
* autodoc: ``__bool__`` method could be called
* autodoc: A typehint for the instance variable having type_comment on
super class is not displayed
* autodoc: a __slots__ attribute is not documented even having docstring
* autodoc: inherited-members doesn't work for instance attributes on super
class
* autosummary: non utf-8 reST files are generated when template contains
multibyte characters
* autosummary: summary extraction splits text after "el at." unexpectedly
* html: Wrong url_root has been generated on a document named "index"
* html search: Do not load ``language_data.js`` in non-search pages
* i18n: ``-D gettext_compact=0`` is no longer working
* graphviz: The layout option for graph and digraph directives don't work
* linkcheck: Use GET when HEAD requests cause Too Many Redirects, to
accommodate infinite redirect loops on HEAD
* Makefile: ``make clean`` with empty BUILDDIR is dangerous
* py domain: ``:type:`` and ``:rtype:`` gives false ambiguous class
lookup warnings
* std domain: Failed to parse an option that starts with bracket
* LaTeX: Prevent page brake in the middle of a seealso
* C, fix copying of AliasNode.
Release 3.3.1 (released Nov 12, 2020)
=====================================
Bugs fixed
----------
* autodoc: autoclass directive became slower than Sphinx-3.2
* autosummary: raise PycodeError when documenting python package
without __init__.py
* autosummary: autosummary_mock_imports causes slow down builds
* C, properly initialize attributes in empty symbols.
* 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
--------------
* html: Show a better error message for failures on copying
html_static_files
* C: added a ``maxdepth`` option to :rst:dir:`c:alias` to insert
nested declarations.
* LaTeX: Allow to add LaTeX package via ``app.add_latex_package()`` until
just before writing .tex file
* manpage: Add :confval:`man_make_section_directory` to make a section
directory on build man page
* epub: Allow to suppress "duplicated ToC entry found" warnings from epub
builder using :confval:`suppress_warnings`.
* sphinx-quickstart: Add :option:`sphinx-quickstart --no-sep` option
* sphinx.testing: Register public markers in sphinx.testing.fixtures
* napoleon: use the obj role for all See Also items
* napoleon: Apply :confval:`napoleon_preprocess_types` to every field
* C and C++, show line numbers for previous declarations when duplicates are
detected.
* Remove substitution_reference nodes from doctree only on LaTeX builds
Bugs fixed
----------
* i18n: Add support for having single text domain
* i18n: Failed to override system message translation
* autodoc: AttributeError is raised when False value is passed to
autodoc_default_options
* autodoc: functools.cached_property is not considered as a property
* autodoc: parsing error is raised if some extension replaces docstring
by string not ending with blank lines
* autodoc: Wrong constructor signature for the class derived from
typing.Generic
* autodoc: TypeError is raised when annotation has invalid __args__
* autodoc: Tuple in default value is wrongly rendered
* autodoc: type aliases break type formatting of autoattribute
* autodoc: can't detect overloaded methods defined in other file
* autodoc: single-string __slots__ is not handled correctly
* autodoc: autodoc_typehints='none' does not effect to overloaded functions
* napoleon: description is disappeared when it contains inline literals
* napoleon: Potential of regex denial of service in google style docs
* LaTeX: pxjahyper loaded even when latex_engine is not platex
* LaTeX: 'oneside' classoption causes build warning
* intersphinx: Potential of regex denial of service by broken inventory
* sphinx-build: missing and redundant spacing (and etc) for console
output on building
* imgconverter: Check availability of imagemagick many times
* py domain: number in default argument value is changed from hexadecimal
to decimal
* html: Prevent arrow keys changing page when button elements are focused
* html search: Fix unnecessary load of images when parsing the document
* html theme: Line numbers misalign with code lines
* The highlight warning has wrong location in some builders (LaTeX,
singlehtml and so on)
* Eliminate Fancyhdr build warnings for oneside documents
* Failed to refer a token in productionlist if it is indented
* linkcheck: Report HTTP errors when ``linkcheck_anchors`` is ``True``
* linkcheck: take source directory into account for local files
* linkcheck: ``tel:`` schema hyperlinks are detected as errors
* linkcheck: An exit status is incorrect when links having unsupported
schema found
* C, add missing items to internal object types dictionary,
e.g., preventing intersphinx from resolving them.
* C, fix anon objects in intersphinx.
* 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.
* figure numbers are unexpectedly assigned to uncaptioned items
* make "inline" line numbers un-selectable
Testing
--------
* Support parallel build in sphinx.testing
Release 3.2.1 (released Aug 14, 2020)
=====================================
Features added
--------------
* napoleon: Add :confval:`napoleon_preprocess_types` to enable the type
preprocessor for numpy style docstrings
* C and C++, parse function attributes after parameters and qualifiers.
Bugs fixed
----------
* napoleon: Crashes during processing C-ext module
* napoleon: "Inline literal start-string without end-string" warning in
Numpy style Parameters section
* autodoc: KeyError is raised on documenting an attribute of the broken
class
* autodoc: AttributeError is raised on documenting an attribute on Python
3.5.2
* autodoc: NameError is raised when target code uses ``TYPE_CHECKING``
* C++, fix parsing of template template paramters
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
:confval:`c_allow_pre_v3` and :confval:`c_warn_on_allowed_pre_v3`.
Features added
--------------
* autodoc: Allow overriding of exclude-members in skip-member function
* autodoc: ``:private-member:`` can take an explicit list of member names
to be documented
* autosummary: Add :confval:`autosummary_filename_map` to avoid conflict
of filenames between two object with different case
* autosummary: Support instance attributes as a target of autosummary
directive
* html: Add :confval:`html_codeblock_linenos_style` to change the style
of line numbers for code-blocks
* C and C++, support parameterized GNU style attributes.
* napoleon: Add aliases Warn and Raise.
* napoleon: parse type strings and make them hyperlinks as possible. The
conversion rule can be updated via :confval:`napoleon_type_aliases`
* napoleon: Create a hyperlink for each the type of parameter when
:confval:`napoleon_use_params` is False
* C, added :rst:dir:`c:alias` directive for inserting copies
of existing declarations.
* html: inventory is broken if the docname contains a space
* html search: Allow searching for numbers
* html theme: Add a new option :confval:`globaltoc_maxdepth` to control
the behavior of globaltoc in sidebar
* i18n: Optimize the dependencies check on bootstrap
* i18n: :confval:`figure_language_filename` supports ``docpath`` token
* linkcheck: Support checks for local links
* setuptools: Link verbosity to distutils' -v and -q option
* doctest: Add ``:trim-doctest-flags:`` and ``:no-trim-doctest-flags:``
options to doctest, testcode and testoutput directives
* 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.
* 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 :confval:`c_allow_pre_v3` to ``True`` to enable this.
The warnings printed from this functionality can be suppressed by setting
:confval:`c_warn_on_allowed_pre_v3`` to ``True``.
The functionality is immediately deprecated.
* C, add support for named variadic macro arguments.
* Allow to suppress "self referenced toctrees" warning
Bugs fixed
----------
* autodoc: TypeError is raised on mocking generic-typed classes
* autodoc: function signature is not shown when the function has a
parameter having ``inspect._empty`` as its default value
* autodoc: type annotations for overloaded functions are not resolved
* autodoc: An instance attribute cause a crash of autofunction directive
* autodoc: ``private-members`` option does not work for class attributes
* autodoc: Generator type annotation is wrongly rendered in py36
* autodoc: An uninitialized annotated instance variable is not documented
when ``:inherited-members:`` option given
* autodoc: A type hint for the instance variable defined at parent class
is not shown in the document of the derived class
* autodoc: An annotated instance variable on super class is not
documented when derived class has other annotated instance variables
* autosummary: cannot handle umlauts in function names
* autosummary: Failed to extract summary line when abbreviations found
* autosummary: Failed to extract correct summary line when docstring
contains a hyperlink target
* autosummary: "Module attributes" header is not translatable
* apidoc: An extra newline is generated at the end of the rst file if a
module has submodules
* napoleon: decorated special methods are not shown
* napoleon: parameters are not escaped for combined params in numpydoc
* napoleon: multiple paramaters declaration in numpydoc was wrongly
recognized when napoleon_use_params=True
* LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links
* html theme: XML-invalid files were generated
* gettext: Wrong source info is shown when using rst_epilog
* linkcheck: HEAD requests are not used for checking
* i18n: Failed to add an explicit title to ``:ref:`` role on translation
* py domain: failed to resolve a type annotation for the attribute
* py domain: failed to parse a type annotation containing ellipsis
* std domain: option directive does not generate old node_id compatible
with 2.x or older
* i18n: The content of ``math`` directive is interpreted as reST on
translation
* i18n: The ``root`` element for :confval:`figure_language_filename` is
not a path that user specifies in the document
* texinfo: TypeError is raised for nested object descriptions
* texinfo: a warning not supporting desc_signature_line node is shown
* :rst:role:`abbr` role without an explanation will show the explanation
from the previous abbr role
* graphviz: graphviz.css was copied on building non-HTML document
* C and C++, removed ``noindex`` directive option as it did
nothing.
* Duplicated node IDs are generated if node has multiple IDs
* Symbols sections are appeared twice in the index page
* Fix circular import in sphinx.addnodes
* CSS: make "highlight" selector more robust
* 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
--------------------
* autodoc: the signature of base function will be shown for decorated
functions, not a signature of decorator
Bugs fixed
----------
* autodoc: Failed to detect module when relative module name given
* autodoc: AttributeError is raised when non-class object is given to
the autoclass directive
* autodoc: KeyError is raised for invalid mark up when autodoc_typehints
is 'description'
* autodoc: crashed if the target name matches to both an attribute and
module that are same name
* autodoc: function signature becomes ``(*args, **kwargs)`` if the
function is decorated by generic decorator
* autosummary: generates broken stub files if the target code contains
an attribute and module that are same name
* viewcode: Failed to resolve viewcode references on 3rd party builders
* html theme: List items have extra vertical space
* html theme: Undesired interaction between "overflow" and "float"
Release 3.1.1 (released Jun 14, 2020)
=====================================
Incompatible changes
--------------------
* napoleon: a type for attribute are represented as typed field
Features added
--------------
* autodoc: Show detailed warning when type_comment is mismatched with its
signature
Bugs fixed
----------
* autodoc: Warnings raised on variable and attribute type annotations
* autodoc: EOFError is raised on parallel build
* autodoc: TypeError is raised for overloaded C-ext function
* autodoc: an object which descriptors returns is unexpectedly documented
* autodoc: wrong signature is shown for the function using contextmanager
* autosummary: generates broken stub files if the target code contains
an attribute and module that are same name
* napoleon: Warnings raised on variable and attribute type annotations
* sphinx.util.inspect causes circular import problem
Release 3.1.0 (released Jun 08, 2020)
=====================================
Dependencies
------------
* mathjax: Update to 2.7.5
Incompatible changes
--------------------
* imgconverter: Invoke "magick convert" command by default on Windows
Deprecated
----------
* The first argument for sphinx.ext.autosummary.generate.AutosummaryRenderer has
been changed to Sphinx object
* ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` takes an object type
as an argument
* The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()``
* The ``template_dir`` argument of ``sphinx.ext.autosummary.generate.
AutosummaryRenderer``
* The ``module`` argument of ``sphinx.ext.autosummary.generate.
find_autosummary_in_docstring()``
* The ``builder`` argument of ``sphinx.ext.autosummary.generate.
generate_autosummary_docs()``
* The ``template_dir`` argument of ``sphinx.ext.autosummary.generate.
generate_autosummary_docs()``
* The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()``
* ``sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()``
* ``sphinx.util.rpartition()``
Features added
--------------
* LaTeX: Make the ``toplevel_sectioning`` setting optional in LaTeX theme
* LaTeX: Allow to override papersize and pointsize from LaTeX themes
* LaTeX: Add :confval:`latex_theme_options` to override theme options
* Allow to suppress "circular toctree references detected" warnings using
:confval:`suppress_warnings`
* C, added scope control directives, :rst:dir:`c:namespace`,
:rst:dir:`c:namespace-push`, and :rst:dir:`c:namespace-pop`.
* autodoc: Suppress default value for instance attributes
* autodoc: consider a member public if docstring contains
``:meta public:`` in info-field-list
* autodoc: Allow to generate docs for singledispatch functions by
py:autofunction
* autodoc: Support final classes and methods
* autodoc: Support signatures defined by ``__new__()``, metaclasses and
builtin base classes
* autodoc: Support multiple signatures on docstring
* autodoc: Support GenericAlias in Python 3.7 or above
* autodoc: Support overloaded functions
* autodoc: Support TypeVar
* autosummary: headings in generated documents are not translated
* autosummary: Add ``:caption:`` option to autosummary directive to set a
caption to the toctree
* autosummary: Support module attributes
* autosummary: Add ``:recursive:`` option to autosummary directive
to generate stub files recursively
* autosummary: Add :confval:`autosummary_context` to add template
variables for custom templates
* html: Support nested <kbd> elements
* html theme: Add right margin to footnote/citation labels
* html theme: CSS spacing for code blocks with captions and line
numbers
* html theme: Add new options :confval:`globaltoc_collapse` and
:confval:`globaltoc_includehidden` to control the behavior of globaltoc in
sidebar
* html theme: Avoid clashes between sidebar and other blocks
* html theme: Relbar breadcrumb should contain current page
* html theme: A canonical URL is not escaped
* html theme: Avoid whitespace at the beginning of genindex.html
* html theme: Add a "clearer" at the end of the "body"
* html theme: Make admonition/topic/sidebar scrollable
* html theme: Add top and bottom margins to tables
* html theme: Add viewport meta tag for basic theme
* 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.
* C++, parse expressions with user-defined literals.
* C++, parse trailing return types.
* py domain: Add ``:final:`` option to :rst:dir:`py:class:`,
:rst:dir:`py:exception:` and :rst:dir:`py:method:` directives
* py domain: Change a type annotation for variables to a hyperlink
* std domain: :rst:dir:`option` directive support arguments in the form
of ``foo[=bar]``
* napoleon: a type for attribute are represented like type annotation
* napoleon: overescaped trailing underscore on attribute
* linkcheck: Add :confval:`linkcheck_request_headers` to send custom HTTP
headers for specific host
* setuptools: Support ``--verbosity`` option
* Add ``allowed_exceptions`` parameter to ``Sphinx.emit()`` to allow
handlers to raise specified exceptions
* C++, parse (trailing) requires clauses.
Bugs fixed
----------
* autodoc: incremental build does not work for imported objects
* autodoc: annotations not to be shown for descriptors
* autodoc: Decorated inherited method has no documentation
* autodoc: The change of autodoc-process-docstring for variables is
cached unexpectedly
* autodoc: misdetects a sync function is async
* autodoc: failed to detect a classmethod on Enum class
* autodoc: a typehint contains spaces is wrongly rendered under
autodoc_typehints='description' mode
* autodoc: failed to import nested class
* autodoc: does not render correct signatures for built-in functions
* autodoc: ``Optional[Union[foo, bar]]`` is presented as
``Union[foo, bar, None]``
* autodoc: autofunction emits an unfriendly warning if an invalid object
specified
* autodoc: undecorated signature is shown for decorated functions
* autodoc: typo in the default value of autodoc_member_order
* autodoc: wrong value for :member-order: option is ignored silently
* autodoc: member-order="bysource" does not work for C module
* autodoc: member-order="bysource" does not work for a module having
__all__
* autodoc: wrong retann value is passed to a handler of
autodoc-proccess-signature
* autodoc: fails with ValueError when processing numpy objects
* autodoc: TypeError is raised on documenting singledispatch function
* autosummary: a nested class is indexed as non-nested class
* autosummary: autosummary directive emits warnings twices if failed to
import the target module
* autosummary: The template variable "members" contains imported members
even if :confval:`autossummary_imported_members` is False
* autosummary: The location of import failure warning is missing
* sphinx-autogen: crashes when custom template uses inheritance
* sphinx-autogen: crashes when template uses i18n feature
* sphinx-build: Wrong error message when outdir is not directory
* sphinx-quickstart: Fix multiple directory creation for nested relpath
* html: Bad alignment of equation links
* html theme: some themes does not respect background color of Pygments
style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and traditional)
* html theme: inconsistent padding in admonitions
* napoleon: bad parsing of inline code in attribute docstrings
* imgconverter: runs imagemagick once unnecessary for builders not
supporting images
* incorrectly renders consecutive backslashes for docutils-0.16
* handle errors on event handlers
* LaTeX: EN DASH disappears from PDF bookmarks in Japanese documents
* LaTeX: Anonymous indirect hyperlink target causes duplicated labels
* LaTeX: pdflatex crashed when URL contains a single quote
* py domain: The default value for positional only argument is not shown
* coverage: Add :confval:`coverage_show_missing_items` to show coverage
result to console
* C++, fix rendering and xrefs in nested names explicitly starting
in global scope, e.g., ``::A::B``.
* C, fix rendering and xrefs in nested names explicitly starting
in global scope, e.g., ``.A.B``.
* 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
----------
* autodoc: parametrized types are shown twice for generic types
* autodoc: system defined TypeVars are shown in Python 3.9
* html: Updated jQuery version from 3.4.1 to 3.5.1 for security reasons
* md5 fails when OpenSSL FIPS is enabled
* 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
----------
* 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 :confval:`c_id_attributes`
and :confval:`c_paren_attributes` to support user-defined attributes.
Bugs fixed
----------
* py domain: fails with IndexError for empty tuple in type annotation
* py domain: keyword-only arguments are documented as having a default of
None
* std domain: :rst:role:`term` role could not match case-insensitively
* autodoc: empty tuple in type annotation is not shown correctly
* autodoc: Sphinx builds has been slower since 3.0.0 on mocking
* C++, fix spacing issue in east-const declarations.
* LaTeX: Xindy language options were incorrect
* sphinx crashes with ImportError on python3.5.1
Release 3.0.1 (released Apr 11, 2020)
=====================================
Incompatible changes
--------------------
* std domain: :rst:dir:`term` role becomes case sensitive
Bugs fixed
----------
* py domain: a reference to class ``None`` emits a nitpicky warning
* py domain: a return annotation ``None`` in the function signature is
not converted to a hyperlink when using intersphinx
* std domain: duplication warning for glossary terms is case insensitive
* C++, fix merging overloaded functions in parallel builds.
* autodoc: fails with ValueError when using autodoc_mock_imports
* autodoc: ``autodoc_typehints='description'`` doesn't suppress typehints
in signature for classes/methods
* autodoc: fails with AttributeError when an object returns non-string
object as a ``__doc__`` member
* crashed when giving a non-string object to logger
* html theme: Do not include xmlns attribute with HTML 5 doctype
* html theme: Escape some links in HTML templates
Release 3.0.0 (released Apr 06, 2020)
=====================================
Dependencies
------------
3.0.0b1
* LaTeX: drop dependency on :program:`extractbb` for image inclusion in
Japanese documents as ``.xbb`` files are unneeded by :program:`dvipdfmx`
since TeXLive2015
* babel-2.0 or above is available (Unpinned)
Incompatible changes
--------------------
3.0.0b1
* Drop features and APIs deprecated in 1.8.x
* autosummary: stub files are overwritten automatically by default. see
:confval:`autosummary_generate_overwrite` to change the behavior
* autodoc: the members of ``object`` class are not documented by default
when ``:inherited-members:`` and ``:special-members:`` are given.
* py domain: ``meta`` fields in info-field-list becomes reserved. They
are not displayed on output document now
* 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 :rst:dir:`productionlist` some uses of
:rst:role:`token` must be modified to include the scope which was previously
ignored.
* 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.
* C++ domain: Non intended behavior is removed such as ``say_hello_``
links to ``.. cpp:function:: say_hello()``
* js domain: Non intended behavior is removed such as ``parseInt_`` links
to ``.. js:function:: parseInt``
* rst domain: Non intended behavior is removed such as ``numref_`` links
to ``.. rst:role:: numref``
* py domain: Non intended behavior is removed such as ``say_hello_``
links to ``.. py:function:: say_hello()``
* 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``.
* double backslashes in domain directives are no longer replaced by
single backslashes as default. A new configuration value
:confval:`strip_signature_backslash` can be used by users to reenable it.
3.0.0 final
* ``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
* autosummary: Add :confval:`autosummary_generate_overwrite` to overwrite
old stub file
* autodoc: ``:inherited-members:`` option takes a name of anchestor class
not to document inherited members of the class and uppers
* autodoc: consider a member private if docstring contains
``:meta private:`` in info-field-list
* autodoc: Support Annotated type (PEP-593)
* autodoc: Support singledispatch functions and methods
* autodoc: :confval:`autodoc_typehints` accepts ``"description"``
configuration. It shows typehints as object description
* apidoc: Propagate ``--maxdepth`` option through package documents
* glossary: emit a warning for duplicated glossary entry
* domain: Register hyperlink target for index page automatically
* std domain: emit a warning for duplicated generic objects
* py domain: Add new event: :event:`object-description-transform`
* py domain: Do not emit nitpicky warnings for built-in types
* py domain: Support lambda functions in function signature
* py domain: Allow to make a style for arguments of functions and methods
* py domain: Emit a warning on describing a python object if the
entry is already added as the same name
* py domain: type annotations in singature are converted to cross refs
* Support priority of event handlers. For more detail, see
:py:meth:`.Sphinx.connect()`
* Implement the scoping for :rst:dir:`productionlist` as indicated
in the documentation.
* Support backslash line continuation in :rst:dir:`productionlist`.
* config: Allow to show an error message from conf.py via ``ConfigError``
* html: :confval:`html_scaled_image_link` will be disabled for images having
``no-scaled-link`` class
* Add CSS class indicating its domain for each desc node
* latex: Use babel for Chinese document when using XeLaTeX
* LaTeX: Support LaTeX Theming (experimental)
* LaTeX: Add LaTeX styling macro for :rst:role:`kbd` role
* genindex: Show "main" index entries at first
* linkcheck: writes all links to ``output.json``
* html search: full text search can be disabled for individual document
using ``:nosearch:`` file-wide metadata
* html search: Allow to override JavaScript splitter via
``SearchLanguage.js_splitter_code``
* 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 :rst:role:`c:expr` for rendering expressions and types
in text.
* Added ``SphinxDirective.get_source_info()``
and ``SphinxRole.get_source_info()``.
* 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.
* 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.
* autodoc: Incorrect handling of nested class names on show-inheritance
* autodoc: error message for invalid directive options has wrong location
* autodoc: info-field-list is wrongly generated from type hints into the
class description even if ``autoclass_content='class'`` set
* autodoc: a cython-function is not recognized as a function
* inheritance_diagram: Incorrect handling of nested class names
* ``code-block:: guess`` does not work
* html: source_suffix containing dot leads to wrong source link
* html: Resizing SVG image fails with ValueError
* html search: Fix use of ``html_file_suffix`` instead of
``html_link_suffix`` in search results
* html theme: ``bizstyle`` does not support ``sidebarwidth``
* singlehtml: Path to images broken when master doc is not in source root
* std domain: Fix whitespaces are suppressed on referring GenericObject
* console: use bright colors instead of bold
* C, parse array types.
* C, parse function pointers even in complex types.
* sphinx-build: Sphinx crashes if output directory exists as a file
* sphinx-build: Ignore bdb.BdbQuit when handling exceptions
* napoleon: Attributes and Methods sections ignore :noindex: option
3.0.0 final
* autosummary: crashed when :confval:`autosummary_generate` is False
* autosummary: raises UnboundLocalError when unknown module given
* C++, alternate operator spellings are now supported.
* C, alternate operator spellings are now supported.
* 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.
* Escape first "!" in a cross reference linking no longer possible
* py domain: The index entry generated by ``py:function`` directive is
different with one from ``index`` directive with "builtin" type
* capital characters are not allowed for node_id
* epub: duplicated node_ids are generated
* html: a width of table was ignored on HTML builder
* Incorrect argument is passed for :event:`env-get-outdated` handlers
* autodoc: a signature of cython-function is not recognized well
* autodoc: ``__wrapped__`` functions are not documented correctly
* intersphinx: ValueError is raised when an extension sets up
:confval:`intersphinx_mapping` on :event:`config-inited` event
* Sphinx builds has been slower since 2.4.0 on debug mode
py-sphinx: updated to 2.4.1 Release 2.4.1: Bugs fixed * html: crashed when on scaling SVG images which have float dimentions * autodoc: TypeError: ‘getset_descriptor’ object is not iterable Release 2.4.0: 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 * inheritance_diagram: Make the background of diagrams transparent * duration: Add sphinx.ext.durations to inspect which documents slow down the build * LaTeX: Support a nested table * LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via environment variable * graphviz: Support :class: option * html: :scale: option of image/figure directive not working for SVG images (imagesize-1.2.0 or above is required) * imgconverter: Support illustrator file (.ai) to .png conversion * autodoc: Support Positional-Only Argument separator (PEP-570 compliant) * autodoc: Support type annotations for variables * autodoc: Add new event: autodoc-before-process-signature * autodoc: Support type_comment style (ex. # type: (str) -> str) annotation (python3.8+ or typed_ast is required) * autodoc: Support instance variables without defaults (PEP-526) * 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 * 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 * py domain: :py:attr: is able to refer properties again * apidoc: Add -q option for quiet mode Bugs fixed * html: Remove redundant type=”text/javascript” from <script> elements * html: SVG image is not layouted as float even if aligned * autodoc: failed to read the source codes encoeded in cp1251 * latex: warning for babel shown twice * latex: LaTeX compilation falls into infinite loop (wrapfig issue) * latex: :reversed: option for toctree does not effect to LaTeX build * Wrong node-ids are generated in glossary directive * apidoc: misdetects module name for .so file inside module * apidoc: private members are not shown even if --private given * apidoc: Support a python package consisted of __init__.so file * napoleon: fails to parse tilde in :exc: role * gettext: Absolute path used in message catalogs * autodoc: nested partial functions are not listed * autodoc: partial functions imported from other modules are listed as module members without :impoprted-members: option * autodoc: Trailing comma in :members:: option causes cryptic warning * autosummary: autosummary_imported_members is ignored on generating a stub file for submodule * linkcheck: redirect is treated as an error * HTML template: If navigation_with_keys option is activated, modifier keys are ignored, which means the feature can interfere with browser features * std domain: Can’t assign numfig-numbers for custom container nodes * std domain: enumerated nodes are marked as duplicated when extensions call note_explicit_target() * dirhtml: Cross references are broken via intersphinx and :doc: role * C++: - Don’t crash when using the struct role in some cases. - Don’t warn when using the var/member role for function parameters. - Render call and braced-init expressions correctly. * Filenames of images generated by sphinx.transforms.post_transforms.images.ImageConverter or its subclasses (used for latex build) are now sanitized, to prevent broken paths
py-sphinx: updated to 2.3.1 Release 2.3.1: Bugs fixed * sphinx-autogen: raises AttributeError Release 2.3.0: Incompatible changes * end-before option of literalinclude directive does not match the first line of the code block. * Change default User-Agent header to "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z". It can be changed via user_agent. * text: content of admonitions starts after a blank line Deprecated sphinx.builders.gettext.POHEADER sphinx.io.SphinxStandaloneReader.app sphinx.io.SphinxStandaloneReader.env sphinx.util.texescape.tex_escape_map sphinx.util.texescape.tex_hl_escape_map_new sphinx.writers.latex.LaTeXTranslator.no_contractions Features added * C++, support bit-fields. * html: Eliminate prompt characters of doctest block from copyable text * html: Use favicon for OpenSearch if available * html theme: agogo theme now supports rightsidebar option * Add PEP-561 Support * latex: Allow to load additonal LaTeX packages via extrapackages key of latex_elements * Add new config variable: user_agent * LaTeX: have backslash also be an inline literal word wrap break character * LaTeX: Support upLaTeX as a new latex_engine (experimental) * Improve a warning message when extensions are not parallel safe * Improve Intersphinx performance for multiple remote inventories. * apidoc: .so file support * autosummary: emit autodoc-skip-member event on generating stub file * i18n: make explicit titles in toctree translatable * linkcheck: Add linkcheck_auth option to provide authentication information when doing linkcheck builds * linkcheck: Handles HTTP 308 Permanent Redirect * html: Wrap section number in span tag * gettext: Add gettext_last_translator' and :confval:`gettext_language_team to customize headers of POT file Bugs fixed * LaTeX: Longtable before header has incorrect distance (refs: latex3/latex2e#173) * LaTeX: Avoid section names at the end of a page * LaTeX: Do not replace unicode characters by LaTeX macros on unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript and subscript digits go through “as is” (as default OpenType font supports them) * linkcheck: Be defensive and handle newly defined HTTP error code * linkcheck: Failure on parsing content * image URLs containing data: causes gettext builder crashed * i18n: Error when compiling message catalogs on Hindi * i18n: KeyError is raised if section title and table title are same * i18n: rst_prolog breaks the translation * mathbase: Some deprecated functions have removed * autodoc: mock object does not work as a class decorator * epub: Wrong internal href fragment links * Allow not to install sphinx.testing as runtime (mainly for ALT Linux) * html: search result was broken with empty html_file_suffix * LaTeX does not wrap long code lines at backslash character * LaTeX: PDF build breaks if admonition of danger type contains code-block long enough not to fit on one page * LaTeX: code-block in a danger type admonition can easily spill over bottom of page * texinfo: Code examples broken following “sidebar” * An orphan warning is emitted for included document on Windows. Thanks to @drillan * Fix smartypants module calls re.sub() with wrong options * HTML search: If a search term is partially matched in the title and fully matched in a text paragraph on the same page, the search does not include this match. * config.py shouldn’t pop extensions from overrides * text: extra spaces are inserted to hyphenated words on folding lines * LaTeX: xelatex converts straight double quotes into right curly ones (shows when smartquotes is False) * LaTeX: even with smartquotes off, PDF output transforms straight quotes and consecutive hyphens into curly quotes and dashes * LaTeX: multi-line display of authors on title page has ragged edges * Sphinx crashes with docutils-0.16b0 * sphinx-build: A console message is wrongly highlighted * sphinx-build: -D option does not considers 0 and 1 as a boolean value
py-sphinx: updated to 2.2.2 Release 2.2.2: Incompatible changes * For security reason of python, parallel mode is disabled on macOS and Python3.8+ Bugs fixed * LaTeX: 2019-10-01 LaTeX release breaks :file:`sphinxcyrillic.sty` * i18n: French, Hindi, Chinese, Japanese and Korean translation messages has been broken * parallel build causes AttributeError on macOS and Python3.8
py-sphinx: updated to 2.2.0
Release 2.2.0:
Incompatible changes
apidoc: template files are renamed to .rst_t
html: Field lists will be styled by grid layout
Deprecated¶
sphinx.domains.math.MathDomain.add_equation()
sphinx.domains.math.MathDomain.get_next_equation_number()
The info and warn arguments of sphinx.ext.autosummary.generate.generate_autosummary_docs()
sphinx.ext.autosummary.generate._simple_info()
sphinx.ext.autosummary.generate._simple_warn()
sphinx.ext.todo.merge_info()
sphinx.ext.todo.process_todo_nodes()
sphinx.ext.todo.process_todos()
sphinx.ext.todo.purge_todos()
Features added
* graphviz: :graphviz_dot: option is renamed to :layout:
* html: emit a warning if html_static_path and html_extra_path directories are inside output directory
* html: Add a label to search input for accessability purposes
* apidoc: Add --templatedir option
* Add override argument to app.add_autodocumenter()
* imgmath: let imgmath_use_preview work also with the SVG format for images rendering inline math
* LaTeX: refactor visit_enumerated_list() to use \sphinxsetlistlabels
* quickstart: Use https://docs.python.org/3/ for default setting of intersphinx_mapping
* sphinx-build: give reasons why rebuilded
Bugs fixed
py domain: duplicated warning does not point the location of source code
* html: Sphinx never updates a copy of html_logo even if original file has changed
* html theme: scrollbar is hard to see on classic theme and macOS
* linkcheck: Consider HTTP 503 response as not an error
* Make generated download links reproducible
* UnboundLocalError is raised if broken extension installed
* autodoc: autodoc_inherit_docstrings does not effect to __init__() and __new__()
* autodoc: autodoc_member_order does not refer order of imports when 'bysource' order
* autodoc: missing type annotation for variadic and keyword parameters
* autodoc: Formatting issues with autodoc_typehints=’none’
* autodoc: crashed when target code contains custom method-like objects
* autosummary: crashed with wrong autosummary_generate setting
* autosummary: crashes without no autosummary_generate setting
* LaTeX: autonumbered list can not be customized in LaTeX since Sphinx 1.8.0
* Failed to load last environment object when extension added
* Invalid sort in pair index
* last_updated wrongly assumes timezone as UTC
* std domain: option directive registers an index entry for each comma separated option
* sphinx-build: Escaped characters in error messages
* doctest comments not getting trimmed since Sphinx 1.8.0
* glossary: Wrong hyperlinks are generated for non alphanumeric terms
* i18n: classifiers of definition list are not translated with docutils-0.15
* DocFieldTransformer raises AttributeError when given directive is not a subclass of ObjectDescription
Release 2.1.2:
Bugs fixed
* custom lexers fails highlighting when syntax error
* info field lists are incorrectly recognized
Release 2.1.1 (released Jun 10, 2019)
Incompatible changes
* autodoc: Stop to generate document for undocumented module variables
Bugs fixed
* LaTeX: admonitions of note type can get separated from immediately preceding section title by pagebreak
* autodoc: crashed when autodocumenting classes with __slots__ = None
* autodoc: generates docs for “optional import”ed modules as variables
* autosummary: crashed when generating document of properties
* napoleon: docstrings for properties are not processed
* napoleon: “Unknown target name” error if variable name ends with underscore
* apidoc: missing blank lines between modules
Release 2.1.0:
Incompatible changes
Ignore filenames without file extension given to Builder.build_specific() API directly
* The anchor of term in glossary directive is changed if it is consisted by non-ASCII characters
* html: Centering tables by default using CSS
* latex: xelatex and xeCJK are used for Chinese documents by default
Sphinx.add_lexer() now takes a Lexer class instead of instance. An instance of lexers are still supported until Sphinx-3.x.
Deprecated
sphinx.builders.latex.LaTeXBuilder.apply_transforms()
sphinx.builders._epub_base.EpubBuilder.esc()
sphinx.directives.Acks
sphinx.directives.Author
sphinx.directives.Centered
sphinx.directives.Class
sphinx.directives.CodeBlock
sphinx.directives.Figure
sphinx.directives.HList
sphinx.directives.Highlight
sphinx.directives.Include
sphinx.directives.Index
sphinx.directives.LiteralInclude
sphinx.directives.Meta
sphinx.directives.Only
sphinx.directives.SeeAlso
sphinx.directives.TabularColumns
sphinx.directives.TocTree
sphinx.directives.VersionChange
sphinx.domains.python.PyClassmember
sphinx.domains.python.PyModulelevel
sphinx.domains.std.StandardDomain._resolve_citation_xref()
sphinx.domains.std.StandardDomain.note_citations()
sphinx.domains.std.StandardDomain.note_citation_refs()
sphinx.domains.std.StandardDomain.note_labels()
sphinx.environment.NoUri
sphinx.ext.apidoc.format_directive()
sphinx.ext.apidoc.format_heading()
sphinx.ext.apidoc.makename()
sphinx.ext.autodoc.importer.MockFinder
sphinx.ext.autodoc.importer.MockLoader
sphinx.ext.autodoc.importer.mock()
sphinx.ext.autosummary.autolink_role()
sphinx.ext.imgmath.DOC_BODY
sphinx.ext.imgmath.DOC_BODY_PREVIEW
sphinx.ext.imgmath.DOC_HEAD
sphinx.transforms.CitationReferences
sphinx.transforms.SmartQuotesSkipper
sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
sphinx.util.node.find_source_node()
sphinx.util.i18n.find_catalog()
sphinx.util.i18n.find_catalog_files()
sphinx.util.i18n.find_catalog_source_files()
For more details, see deprecation APIs list.
Features added
Add a helper class sphinx.transforms.post_transforms.SphinxPostTransform
Add helper methods
PythonDomain.note_module()
PythonDomain.note_object()
SphinxDirective.set_source_info()
* Support --keep-going with BuildDoc setup command
math directive now supports :class: option
todo: todo directive now supports :name: option
Enable override via environment of SPHINXOPTS and SPHINXBUILD Makefile variables
* autodoc: Unable to document bound instance methods exported as module functions
* autodoc: autodoc_default_options now supports imported-members option
* autodoc: Support coroutine
* autodoc: Support abstractmethod
* autodoc: Support attributes in __slots__. For dict-style __slots__, autodoc considers values as a docstring of the attribute
* autodoc: Add autodoc_typehints to suppress typehints from signature
* autodoc: automodule directive now handles undocumented module level variables
* autosummary: Add autosummary_imported_members to display imported members on autosummary
* make clean is catastrophically broken if building into ‘.’
* Support %O% environment variable in make.bat
* py domain: Add :async: option to py:function directive
* py domain: Add new options to py:method directive
:abstractmethod:
:async:
:classmethod:
:property:
:staticmethod:
rst domain: Add directive:option directive to describe the option for directive
* html: Add a label to search form for accessability purposes
* html: Consistent and semantic CSS for signatures
* The rawsource property of production nodes now contains the full production rule
* autosectionlabel: Allow suppression of warnings
coverage: Support a new coverage_ignore_pyobjects option
* latex: Support to build Chinese documents
Bugs fixed
* Inappropriate node_id has been generated by glossary directive if term is consisted by non-ASCII characters
* ifconfig: contents after headings are not shown
commented term in glossary directive is wrongly recognized
* rst domain: rst:directive directive generates waste space
* py domain: Module index (py-modindex.html) has duplicate titles
* man: invalid output when doctest follows rubric
* “Hyperlink target is not referenced” message is shown even if referenced
* autodoc: tab_width setting of docutils has been ignored
* autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
* autosummary: autosummary table gets confused by complex type hints
* autosummary: confused by an argument having some kind of default value
Generated Makefiles lack a final EOL
* extlinks: Cannot escape angle brackets in link caption
* linkcheck: Send commonly used User-Agent
* html search: failed to search document with haiku and scrolls themes
* html search: Fix the ranking of search results
* Wrong year is returned for SOURCE_DATE_EPOCH
* image directive crashes by unknown image format
* C++, allow 8 and 9 in hexadecimal integer literals.
* Fix the string in quickstart for ‘path’ argument of parser
LaTeX: Figures in admonitions produced errors
Release 2.0.1:
Bugs fixed
LaTeX: some system labels are not translated
RemovedInSphinx30Warning is marked as pending
deprecation warnings are not emitted
sphinx.application.CONFIG_FILENAME
sphinx.builders.htmlhelp
viewcode_import
* C++, properly parse full xrefs that happen to have a short xref as prefix
* napoleon: AttributeError is raised for raised section having references
* circular import error on importing SerializingHTMLBuilder
* LaTeX: ‘releasename’ setting for latex_elements is ignored
* html: Search function is broken with 3rd party themes
* html: HTML5Translator crashed with invalid field node
* html theme: The style of field lists has changed in bizstyle theme
Release 2.0.0:
Dependencies
2.0.0b1
LaTeX builder now depends on TeX Live 2015 or above.
LaTeX builder (with 'pdflatex' latex_engine) will process Unicode Greek letters in text (not in math mark-up) via the text font and will not escape them to math mark-up. See the discussion of the 'fontenc' key of latex_elements; such (optional) support for Greek adds, for example on Ubuntu xenial, the texlive-lang-greek and (if default font set-up is not modified) cm-super(-minimal) as additional Sphinx LaTeX requirements.
LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex' requires (by default) the FreeFont fonts, which in Ubuntu xenial are provided by package fonts-freefont-otf, and e.g. in Fedora 29 via package texlive-gnu-freefont.
requests 2.5.0 or above
The six package is no longer a dependency
The sphinxcontrib-websupport package is no longer a dependency
Some packages are separated to sub packages:
sphinxcontrib.applehelp
sphinxcontrib.devhelp
sphinxcontrib.htmlhelp
sphinxcontrib.jsmath
sphinxcontrib.serializinghtml
sphinxcontrib.qthelp
Incompatible changes
2.0.0b1
Drop python 2.7 and 3.4 support
Drop docutils 0.11 support
Drop features and APIs deprecated in 1.7.x
The default setting for master_doc is changed to 'index' which has been longly used as default of sphinx-quickstart.
LaTeX: Move message resources to sphinxmessage.sty
LaTeX: Stop using \captions<lang> macro for some labels
LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts as default choice
LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to FreeMono character width) like 'pdflatex' already did (due to Courier character width). You may need to adjust this via latex_elements 'fvset' key, in case of usage of some other OpenType fonts
LaTeX: Greek letters in text are not escaped to math mode mark-up, and they will use the text font not the math font. The LGR font encoding must be added to the 'fontenc' key of latex_elements for this to work (only if it is needed by the document, of course).
LaTeX: setting the language to 'en' triggered Sonny option of fncychap, now it is Bjarne to match case of no language specified.
* doctest: Follow highlight_language on highlighting doctest block. As a result, they are highlighted as python3 by default.
The order of argument for HTMLTranslator, HTML5Translator and ManualPageTranslator are changed
LaTeX: hard-coded redefinitions of \l@section and \l@subsection formerly done during loading of 'manual' docclass get executed later, at time of \sphinxtableofcontents. This means that custom user definitions from LaTeX preamble now get overwritten. Use \sphinxtableofcontentshook to insert custom user definitions. See Macros.
quickstart: Simplify generated conf.py
* quickstart: some questions are removed. They are still able to specify via command line options
websupport: unbundled from sphinx core. Please use sphinxcontrib-websupport
C++, the visibility of base classes is now always rendered as present in the input. That is, private is now shown, where it was ellided before.
LaTeX: graphics inclusion of oversized images rescales to not exceed the text width and height, even if width and/or height option were used.
epub: epub_title defaults to the project option
* All tables and figures without align option are displayed to center
* html: Output HTML5 by default
2.0.0b2
texinfo: image files are copied into name-figure directory
Deprecated
2.0.0b1
Support for evaluating Python 2 syntax is deprecated. This includes configuration files which should be converted to Python 3.
The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_container(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and EpubBuilder.build_epub()
The arguments of Epub3Builder.build_navigation_doc()
The config variables
html_experimental_html5_writer
The encoding argument of autodoc.Documenter.get_doc(), autodoc.DocstringSignatureMixin.get_doc(), autodoc.DocstringSignatureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc() are deprecated.
The importer argument of sphinx.ext.autodoc.importer._MockModule
The nodetype argument of sphinx.search.WordCollector. is_meta_keywords()
The suffix argument of env.doc2path() is deprecated.
The string style base argument of env.doc2path() is deprecated.
The fallback to allow omitting the filename argument from an overridden IndexBuilder.feed() method is deprecated.
sphinx.addnodes.abbreviation
sphinx.application.Sphinx._setting_up_extension
sphinx.builders.epub3.Epub3Builder.validate_config_value()
sphinx.builders.html.SingleFileHTMLBuilder
sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
sphinx.cmd.quickstart.term_decode()
sphinx.cmd.quickstart.TERM_ENCODING
sphinx.config.check_unicode()
sphinx.config.string_classes
sphinx.domains.cpp.DefinitionError.description
sphinx.domains.cpp.NoOldIdError.description
sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
sphinx.ext.autodoc.importer._MockImporter
sphinx.ext.autosummary.Autosummary.warn()
sphinx.ext.autosummary.Autosummary.genopt
sphinx.ext.autosummary.Autosummary.warnings
sphinx.ext.autosummary.Autosummary.result
sphinx.ext.doctest.doctest_encode()
sphinx.io.SphinxBaseFileInput
sphinx.io.SphinxFileInput.supported
sphinx.io.SphinxRSTFileInput
sphinx.registry.SphinxComponentRegistry.add_source_input()
sphinx.roles.abbr_role()
sphinx.roles.emph_literal_role()
sphinx.roles.menusel_role()
sphinx.roles.index_role()
sphinx.roles.indexmarkup_role()
sphinx.testing.util.remove_unicode_literal()
sphinx.util.attrdict
sphinx.util.force_decode()
sphinx.util.get_matching_docs()
sphinx.util.inspect.Parameter
sphinx.util.jsonimpl
sphinx.util.osutil.EEXIST
sphinx.util.osutil.EINVAL
sphinx.util.osutil.ENOENT
sphinx.util.osutil.EPIPE
sphinx.util.osutil.walk()
sphinx.util.PeekableIterator
sphinx.util.pycompat.NoneType
sphinx.util.pycompat.TextIOWrapper
sphinx.util.pycompat.UnicodeMixin
sphinx.util.pycompat.htmlescape
sphinx.util.pycompat.indent
sphinx.util.pycompat.sys_encoding
sphinx.util.pycompat.terminal_safe()
sphinx.util.pycompat.u
sphinx.writers.latex.ExtBabel
sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
sphinx.writers.text.TextTranslator._make_depart_admonition()
template variables for LaTeX template
logo
numfig_format
pageautorefname
translatablestrings
For more details, see deprecation APIs list.
Features added
2.0.0b1
* The search results preview of generated HTML documentation is reader-friendlier: instead of showing the snippets as raw reStructuredText markup, Sphinx now renders the corresponding HTML. This means the Sphinx extension Sphinx: pretty search results is no longer necessary. Note that changes to the search function of your custom or 3rd-party HTML template might overwrite this improvement.
* autodoc: Support suppress_warnings
* autodoc: autodoc_default_options supports member-order
* autodoc: Display readable names in type annotations for mocked objects
* autodoc: autodoc_default_options accepts True as a value
* autodoc: Add autodecorator directive for decorators
* autosummary: Add autosummary_mock_imports to mock external libraries on importing targets
* htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
* text: Support complex tables (colspan and rowspan)
LaTeX: support rendering (not in math, yet) of Greek and Cyrillic Unicode letters in non-Cyrillic document even with 'pdflatex' as latex_engine
* The versionadded, versionchanged and deprecated directives are now generated with their own specific CSS classes (added, changed and deprecated, respectively) in addition to the generic versionmodified class.
* apidoc: Add –extensions option to sphinx-apidoc
* C++, added an alias directive for inserting lists of declarations, that references existing declarations (e.g., for making a synopsis).
C++: add cpp:struct to complement cpp:class.
* the HTML search considers words that contain a search term of length three or longer a match.
* epub: Show warning for duplicated ToC entries
* Allow to omit an argument for code-block directive. If omitted, it follows highlight or highlight_language
* html: Add html4_writer to use old HTML4 writer
* HTML search: A placeholder for the search summary prevents search result links from changing their position when the search terminates. This makes navigating search results easier.
* linkcheck also checks remote images exist
* githubpages: create CNAME file for custom domains when html_baseurl set
* autosectionlabel: restrict the labeled sections by new config value; autosectionlabel_maxdepth
Bugs fixed
2.0.0b1
* LaTeX: writer should not translate Greek unicode, but use textgreek package
* LaTeX: PDF does not build with default font config for Russian language and 'xelatex' or 'lualatex' as latex_engine
* LaTeX: Greek letters in section titles disappear from PDF bookmarks
* LaTeX: Unicode Greek letters in math directive break PDF build (fix requires extra set-up, see latex_elements 'textgreek' key and/or latex_engine setting)
* LaTeX: should the Bjarne style of fncychap be used for English also if passed as language option?
* LaTeX: (lualatex only) escaping of > by \textgreater{} is not enough as \textgreater{}\textgreater{} applies TeX-ligature
LaTeX: project name is not escaped if latex_documents omitted
LaTeX: authors are not shown if latex_documents omitted
HTML: Invalid HTML5 file is generated for a glossary having multiple terms for one description
QtHelp: OS dependent path separator is used in .qhp file
HTML search: search always returns nothing when multiple search terms are used and one term is shorter than three characters
2.0.0b2
* html: Anchor links are not added to figures
* html: Defer searchindex.js rather than loading it via ajax
* html: Table cells and list items have large margins
* linenothreshold option for highlight directive was ignored
texinfo: make install-info causes syntax error
texinfo: make install-info fails on macOS
* texinfo: image files are not copied on make install-info
* A cross reference in heading is rendered as literal
* C++, fix cpp:alias problems in LaTeX (and singlehtml)
* classes attribute of citation_reference node is lost
AssertionError is raised when custom citation_reference node having classes attribute refers missing citation
* Support code directive
C++, fix parsing of braced initializers.
* AttributeError is raised for old styled index nodes
* inheritance_diagram: correctly describe behavior of parts option in docs, allow negative values.
* i18n: Captions missing in translations for hidden TOCs
2.0.0 final
* py domain: unexpected prefix is generated
Testing
2.0.0b1
Stop to use SPHINX_TEST_TEMPDIR envvar
2.0.0b2
Add a helper function: sphinx.testing.restructuredtext.parse()
py-sphinx: updated to 1.8.3
Release 1.8.3:
Features added
* LaTeX: it is possible to insert custom material to appear on back of title
page, see discussion of 'maketitle' key of :confval:latex_elements
('manual' docclass only)
Bugs fixed
* mathjax: Use CDN URL for "latest" version by default
* html search does not work with some 3rd party themes
* LaTeX, caption package incompatibility since Sphinx 1.6
* autodoc: incremental build is broken when builtin modules are imported
* qthelp: index.html missing in QtHelp
* linkcheck: crashes for a hyperlink containing multibyte character
* DOC: Fix some mistakes in :doc:/latex
* LaTeX: sphinxVerbatim requires explicit "hllines" set-up since 1.6.6
* C++, fix parsing of floating point literals.
* C++, fix assertion in partial builds with duplicates.
* quickstart: sphinx-quickstart fails when $LC_ALL is empty
* Default conf.py is not PEP8-compliant
* LaTeX: document class \maketitle is overwritten with no
possibility to use original meaning in place of Sphinx custom one
* apidoc: wrong help for --tocfile
* todo: crashed if todo is defined in TextElement
* htmlhelp: convert hex escaping to decimal escaping in .hhc/.hhk files
* htmlhelp: broken .hhk file generated when title contains a double quote
py-sphinx: updated to 1.8.0
Release 1.8.0:
Dependencies
1.8.0b1
* LaTeX: :confval:latex_use_xindy, if True (default for
xelatex/lualatex), instructs make latexpdf to use :program:xindy
for general index. Make sure your LaTeX distribution includes it.
Incompatible changes
1.8.0b2
* html theme: refer pygments_style settings of HTML themes
preferentially
* The URL of download files are changed
* quickstart: Makefile and make.bat are not overwritten if exists
1.8.0b1
* the :py:mod:sphinx.ext.graphviz: extension runs dot in the
directory of the document being built instead of in the root directory of
the documentation.
* extensions which stores any data to environment should return the
version of its env data structure as metadata. In detail, please see
:ref:ext-metadata.
* Sphinx expects source parser modules to have supported file formats as
Parser.supported attribute
* The default value of :confval:epub_author and :confval:epub_publisher are
changed from 'unknown' to the value of :confval:author. This is same as
a conf.py file sphinx-build generates.
* The gettext_compact attribute is removed from document.settings
object. Please use config.gettext_compact instead.
* The processing order on reading phase is changed. smart_quotes, sphinx
domains, :event:doctree-read event and versioning doctrees are invoked
earlier than so far. For more details, please read a description of
:py:meth:.Sphinx.add_transform()
* All substitution_definition nodes are removed from doctree on
reading phase
* docutils.conf on $HOME and /etc directories are ignored. Only
docutils.conf on confdir is refered.
* :samp: role supports to escape curly braces with backslash
* The files under :confval:html_static_path are excluded from source
files.
* latex: Use \sphinxcite for citation references instead \hyperref
* The config value viewcode_import is renamed to
:confval:viewcode_follow_imported_members
* latex: :confval:latex_show_pagerefs does not add pagerefs for
citations
* latex: Now "rubric" elements are rendered as unnumbered section title
* html: The anchor for productionlist tokens has been changed
* Modifying a template variable script_files in templates is allowed now.
Please use app.add_js_file() instead.
* Save environment object also with only new documents
* qthelp builder allows dashes in :confval:qthelp_namespace
* LaTeX: with lualatex or xelatex use by default :program:xindy as
UTF-8 able replacement of :program:makeindex. After
upgrading Sphinx, please clean latex build repertory of existing project
before new build.
* html: hlist items are now aligned to top
* highlightlang directive is processed on resolving phase
* latex: LaTeX template has been chaned. Following elements are moved
into the template:
- \begin{document}
- shorthandoff variable
- maketitle variable
- tableofcontents variable
Deprecated
1.8.0b2
* sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
* sphinx.io.SphinxI18nReader.line is deprecated
* sphinx.util.i18n.find_catalog_source_file() has changed; the
*gettext_compact* argument has been deprecated
* sphinx.util.images.guess_mimetype() has changed; the *content*
argument has been deprecated
1.8.0b1
* :confval:source_parsers is deprecated
* :confval:autodoc_default_flags is deprecated
* quickstart: --epub option becomes default, so it is deprecated
* Drop function based directive support. For now, Sphinx only supports class
based directives.
* sphinx.util.docutils.directive_helper() is deprecated
* sphinx.cmdline is deprecated
* sphinx.make_mode is deprecated
* sphinx.locale.l_() is deprecated
* helper function warn() for HTML themes is deprecated
* app.override_domain() is deprecated
* app.add_stylesheet() is deprecated
* app.add_javascript() is deprecated
* app.import_object() is deprecated
* app.add_source_parser() has changed; the *suffix* argument has been
deprecated
* sphinx.versioning.prepare() is deprecated
* Config.__init__() has changed; the *dirname*, *filename* and *tags*
argument has been deprecated
* Config.check_types() is deprecated
* Config.check_unicode() is deprecated
* sphinx.application.CONFIG_FILENAME is deprecated
* highlightlang directive is deprecated
* BuildEnvironment.load() is deprecated
* BuildEnvironment.loads() is deprecated
* BuildEnvironment.frompickle() is deprecated
* env.read_doc() is deprecated
* env.update() is deprecated
* env._read_serial() is deprecated
* env._read_parallel() is deprecated
* env.write_doctree() is deprecated
* env._nitpick_ignore is deprecated
* env.versionchanges is deprecated
* env.dump() is deprecated
* env.dumps() is deprecated
* env.topickle() is deprecated
* env.note_versionchange() is deprecated
* sphinx.writers.latex.Table.caption_footnotetexts is deprecated
* sphinx.writers.latex.Table.header_footnotetexts is deprecated
* sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
* sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is deprecated
* sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
* sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
* sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is deprecated
* sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is deprecated
* sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is deprecated
* sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is deprecated
* sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is deprecated
* sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
* sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
* sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
* sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
* sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
* sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
* sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is deprecated
* sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
* sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
* sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
* sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is deprecated
* sphinx.ext.mathbase extension is deprecated
* sphinx.ext.mathbase.math node is deprecated
* sphinx.ext.mathbase.displaymath node is deprecated
* sphinx.ext.mathbase.eqref node is deprecated
* sphinx.ext.mathbase.is_in_section_title() is deprecated
* sphinx.ext.mathbase.MathDomain is deprecated
* sphinx.ext.mathbase.setup_math() is deprecated
* sphinx.directives.other.VersionChanges is deprecated
* sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
* sphinx.ext.mathbase.get_node_equation_number() is deprecated
* sphinx.ext.mathbase.wrap_displaymath() is deprecated
* The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
is deprecated
Features added
1.8.0b2
* Ensure frozen object descriptions are reproducible
* apidoc: Add --tocfile option to change the filename of ToC
1.8.0b1
* Add :event:config-inited event
* Add sphinx.config.Any to represent the config value accepts any type of
value
* :confval:source_suffix allows a mapping fileext to file types
* Add :confval:author as a configuration value
* imgconverter: Support to convert GIF to PNG
* sphinx-build command supports i18n console output
* Add app.add_message_catalog() and sphinx.locale.get_translations() to
support translation for 3rd party extensions
* helper function warning() for HTML themes is added
* Add Domain.enumerable_nodes to manage own enumerable nodes for domains
(experimental)
* Add a new keyword argument override to Application APIs
* LaTeX: new key 'fvset' for :confval:latex_elements. For
XeLaTeX/LuaLaTeX its default sets fanvyvrb to use normal, not small,
fontsize in code-blocks
* Add :confval:html_css_files and :confval:epub_css_files for adding CSS
files from configuration
* Add :confval:html_js_files for adding JS files from configuration
* Ensure set object descriptions are reproducible.
* Allow to override :confval:numfig_format partially. Full definition
is not needed.
* Improve warning messages during including
* LaTeX: separate customizability of :rst:role:guilabel and
:rst:role:menuselection
* Add Config.read() classmethod to create a new config object from
configuration file
* Wrap graphviz diagrams in <div> tag
* viewcode: Add :event:viewcode-find-source and
:event:viewcode-follow-imported to load source code without loading
* napoleon: Add strings to translation file for localisation
* Display a warning when invalid values are passed to linenothreshold
option of highlight directive
* C++:
- Add a cpp:texpr role as a sibling to cpp:expr.
- Add support for unions.
- add support for anonymous entities using names staring with @.
- add support for (most) character literals.
- Cross-referencing entities inside primary templates is supported,
and now properly documented.
- add new cross-referencing format for cpp:any and cpp:func roles,
for referencing specific function overloads.
* MathJax should be loaded with async attribute
* html: Output canonical_url metadata if :confval:html_baseurl set
* autosummary: expose inherited_members to template
* mathjax: Add :confval:mathjax_options to give options to script tag
for mathjax
* latex: Don't overwrite .tex file if document not changed
* latex: Add alphanumeric enumerated list support
* Add :confval:latex_use_xindy for UTF-8 savvy indexing, defaults to True
if :confval:latex_engine is 'xelatex' or 'lualatex'.
* SphinxLoggerAdapter.info() now supports location parameter
* setuptools: support nitpicky option
* autoclass directive supports nested class
* Add app.add_html_math_renderer() to register a math renderer for HTML
* Apply :confval:trim_doctest_flags to all builders (cf. text, manpages)
* linkcheck: Add better Accept header to HTTP client
* sphinx-build: Add --keep-going option to show all warnings
* Add :rst:role:math:numref role to refer equations (Same as :rst:role:eq)
* quickstart: epub builder is enabled by default
* Add :confval:singlehtml_sidebars to configure sidebars for singlehtml
builder
* doctest: Skip doctest conditionally
* autodoc: emit a warning for invalid typehints
* autodoc: Add :confval:autodoc_default_options which accepts
option values as dict
Bugs fixed
1.8.0b2
* html: search box overrides to other elements if scrolled
* i18n: warnings for translation catalogs have wrong line numbers
* latex: cross references has been broken by multiply labeled objects
* C++, fixes for symbol addition and lookup. Lookup should no longer break
in partial builds.
* download reference to remote file is not displayed
* html theme: pygments_style of theme was overrided by conf.py
by default
* toctree shows confusible warning when document is excluded
* autodoc: :members: causes :special-members: not to be shown
* autodoc: ImportError is replaced by AttributeError for deeper module
* Incorrect links with :download:, duplicate names, and
parallel builds
* autodoc: failed to analyze source code in egg package
* Sphinx crashes if unknown po file exists
1.8.0b1
* i18n: message catalogs were reset on each initialization
* latex: footnote inside footnote was not rendered
* i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks
to Shengjing Zhu.
* productionlist directive generates invalid IDs for the tokens
* (lualatex) PDF build fails if indexed word starts with Unicode character
* latex: index headings "Symbols" and "Numbers" not internationalized
* sphinx-build: Handle errors on scanning documents
* epub: spine has been broken when "self" is listed on toctree
* autosummary does not understand docstring of module level attributes
* C++, prevent nested declarations in functions to avoid lookup problems.
* C++, add missing isPack method for certain template parameter types.
* C++, parse attributes on declerators as well.
* C++, parse delete expressions and basic new expressions as well.
* graphviz: SVGs do not adapt to the column width
Features removed
1.8.0b1
* sphinx.ext.pngmath extension
Documentation
1.8.0b1
* Fix wrong make.bat option for internationalization.
* napoleon: add admonitions added by 4613 to the docs.
py-sphinx: updated to 1.7.3 1.7.3: Bugs fixed * autodoc loses the first staticmethod parameter * autosummary: too wide two column tables in PDF builds * Latex customization via _templates/longtable.tex_t is broken * imgconverter: confused by convert.exe of Windows * On windows, Sphinx crashed when drives of srcdir and outdir are different * autodoc ignores type annotated variables * wrong URLs on warning messages * latex: latex_show_urls assigns incorrect footnote numbers if hyperlinks exists inside substitutions * latex with class memoir Error: Font command \sf is not supported * latex: too slow in proportion to number of auto numbered footnotes * htmlhelp: The entries in .hhp file is not ordered * toctree directive tries to glob for URL having query_string * html search: Upper characters problem in German * latex: Compilation for German docs failed with LuaLaTeX and XeLaTeX * duplicated labels detector does not work well in parallel build * Crashed with extension which returns invalid metadata
py-sphinx: updated to 1.7.2 Release 1.7.2: Incompatible changes * apidoc: folders with an empty __init__.py are no longer excluded from TOC Bugs fixed * sphinx.build_main and sphinx.make_main throw NameError * autosummary emits meaningless warnings * autodoc: crashed when invalid options given * pydomain: always strip parenthesis if empty * autosummary: unexpectedly strips docstrings containing “i.e.” * viewcode: Misplaced <div> in viewcode html output * Don’t require numfig to use :numref: on sections * Option clash for package textcomp * Sphinx does not work with python 3.5.0 and 3.5.1 * Generation PDF file with TexLive on Windows, file not found error * vertical space before equation in latex * message when an image is mismatched for builder is not clear * Incomplete localization strings in Polish and Chinese * Sphinx crashes when error is happens in rendering HTML pages * Error to download remote images having long URL * sphinx/pycode/__init__.py raises AttributeError * qthelp builder should htmlescape keywords * epub: Fix docTitle elements of toc.ncx is not escaped * apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
py-sphinx: updated to 1.7.1 Release 1.7.1: Deprecated 4623: sphinx.build_main() is deprecated. Use sphinx.cmd.build.build_main() instead. autosummary: The interface of sphinx.ext.autosummary.get_documenter() has been changed (Since 1.7.0) 4664: sphinx.ext.intersphinx.debug() is deprecated. Use sphinx.ext.intersphinx.inspect_main() instead. Bugs fixed 4608: epub: Invalid meta tag is generated 4260: autodoc: keyword only argument separator is not disappeared if it is appeared at top of the argument list 4622: epub: epub_scheme does not effect to content.opf 4627: graphviz: Fit graphviz images to page 4617: quickstart: PROJECT_DIR argument is required 4623: sphinx.build_main no longer exists in 1.7.0 4615: The argument of sphinx.build has been changed in 1.7.0 autosummary: The interface of sphinx.ext.autosummary.get_documenter() has been changed 4630: Have order on msgids in sphinx.pot deterministic 4563: autosummary: Incorrect end of line punctuation detection 4577: Enumerated sublists with explicit start with wrong number 4641: A external link in TOC cannot contain “?” with :glob: option C++, add missing parsing of explicit casts and typeid in expression parsing. C++, add missing parsing of this in expression parsing. 4655: Fix incomplete localization strings in Polish 4653: Fix error reporting for parameterless ImportErrors 4664: Reading objects.inv fails again 4662: any refs with term targets crash when an ambiguity is encountered
py-sphinx: updated to 1.6.7 Release 1.6.7: Bugs fixed ---------- * 1922: html search: Upper characters problem in French * 4412: Updated jQuery version from 3.1.0 to 3.2.1 * 4438: math: math with labels with whitespace cause html error * 2437: make full reference for classes, aliased with "alias of" * 4434: pure numbers as link targets produce warning * 4477: Build fails after building specific files * 4449: apidoc: include "empty" packages that contain modules * 3917: citation labels are tranformed to ellipsis * 4501: graphviz: epub3 validation error caused if graph is not clickable * 4514: graphviz: workaround for wrong map ID which graphviz generates * 4525: autosectionlabel does not support parallel build * 3953: Do not raise warning when there is a working intersphinx inventory * 4487: math: ValueError is raised on parallel build. Thanks to jschueller. * 2372: autosummary: invalid signatures are shown for type annotated functions * 3942: html: table is not aligned to center even if :align: center
py-sphinx: update to 1.6.4 Release 1.6.4: Features added * 3926: Add autodoc_warningiserror to suppress the behavior of -W option during importing target modules on autodoc Bugs fixed * 3924: docname lost after dynamically parsing RST in extension * 3946: Typo in sphinx.sty (this was a bug with no effect in default context) * pep: and :rfc: does not supports default-role directive (refs: 3960) * 3960: default_role = ‘guilabel’ not functioning * Missing texinputs_win/Makefile to be used in latexpdf builder on windows. * 4026: nature: Fix macOS Safari scrollbar color * 3877: Fix for C++ multiline signatures. * 4006: Fix crash on parallel build * 3969: private instance attributes causes AttributeError * 4041: C++, remove extra name linking in function pointers. * 4038: C, add missing documentation of member role. * 4044: An empty multicolumn cell causes extra row height in PDF output * 4049: Fix typo in output of sphinx-build -h * 4062: hashlib.sha1() must take bytes, not unicode on Python 3 * Avoid indent after index entries in latex (refs: 4066) * 4070: crashes when the warning message contains format strings * 4067: Return non-zero exit status when make subprocess fails * 4055: graphviz: the :align: option does not work for SVG output * 4055: graphviz: the :align: center option does not work for latex output * 4051: warn() function for HTML theme outputs ‘None’ string
Release 1.6.1 (released May 16, 2017) ===================================== Dependencies ------------ 1.6b1 * (updated) latex output is tested with Ubuntu trusty's texlive packages (Feb. 2014) and earlier tex installations may not be fully compliant, particularly regarding Unicode engines xelatex and lualatex * (added) latexmk is required for ``make latexpdf`` on Unix-like platforms Incompatible changes -------------------- 1.6b1 * 1061, 2336, 3235: Now generation of autosummary doesn't contain imported members by default. Thanks to Luc Saffre. * LaTeX ``\includegraphics`` command isn't overloaded: only ``\sphinxincludegraphics`` has the custom code to fit image to available width if oversized. * The subclasses of ``sphinx.domains.Index`` should override ``generate()`` method. The default implementation raises NotImplementedError * LaTeX positioned long tables horizontally centered, and short ones flushed left (no text flow around table.) The position now defaults to center in both cases, and it will obey Docutils 0.13 ``:align:`` option (refs 3415, 3377) * option directive also allows all punctuations for the option name (refs: 3366) * 3413: if :rst:dir:`literalinclude`'s ``:start-after:`` is used, make ``:lines:`` relative (refs 3412) * ``literalinclude`` directive does not allow the combination of ``:diff:`` option and other options (refs: 3416) * LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine = 'lualatex'`` be used only on up-to-date TeX installs (refs 3070, 3466) * :confval:`latex_keep_old_macro_names` default value has been changed from ``True`` to ``False``. This means that some LaTeX macros for styling are by default defined only with ``\sphinx..`` prefixed names. (refs: 3429) * Footer "Continued on next page" of LaTeX longtable's now not framed (refs: 3497) * 3529: The arguments of ``BuildEnvironment.__init__`` is changed * 3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms only) * 3558: Emit warnings if footnotes and citations are not referenced. The warnings can be suppressed by ``suppress_warnings``. * latex made available (non documented) colour macros from a file distributed with pdftex engine for Plain TeX. This is removed in order to provide better support for multiple TeX engines. Only interface from ``color`` or ``xcolor`` packages should be used by extensions of Sphinx latex writer.
Release 1.5.5 Bugs fixed * 3597: python domain raises UnboundLocalError if invalid name given * 3599: Move to new Mathjax CDN
List files only once.
Release 1.5.1 (released Dec 13, 2016) ===================================== Features added -------------- * 3214: Allow to suppress "unknown mimetype" warnings from epub builder using :confval:`suppress_warnings`. Bugs fixed ---------- * 3195: Can not build in parallel * 3198: AttributeError is raised when toctree has 'self' * 3211: Remove untranslated sphinx locale catalogs (it was covered by untranslated it_IT) * 3212: HTML Builders crashes with docutils-0.13 * 3207: more latex problems with references inside parsed-literal directive (``\DUrole``) * 3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14) * 3220: KeyError when having a duplicate citation * 3200: LaTeX: xref inside desc_name not allowed * 3228: ``build_sphinx`` command crashes when missing dependency * 2469: Ignore updates of catalog files for gettext builder. Thanks to Hiroshi Ohkubo. * 3183: Randomized jump box order in generated index page.
Release 1.4.1: Incompatible changes -------------------- * The default format of `today_fmt` and `html_last_updated_fmt` is back to strftime format again. Locale Date Markup Language is also supported for backward compatibility until Sphinx-1.5. Translations ------------ * Added Welsh translation, thanks to Geraint Palmer. * Added Greek translation, thanks to Stelios Vitalis. * Added Esperanto translation, thanks to Dinu Gherman. * Added Hindi translation, thanks to Purnank H. Ghumalia. * Added Romanian translation, thanks to Razvan Stefanescu. Bugs fixed ---------- * C++, added support for ``extern`` and ``thread_local``. * C++, type declarations are now using the prefixes ``typedef``, ``using``, and ``type``, depending on the style of declaration. * 2413: C++, fix crash on duplicate declarations * 2394: Sphinx crashes when html_last_updated_fmt is invalid * 2408: dummy builder not available in Makefile and make.bat * 2412: hyperlink targets are broken in LaTeX builder * figure directive crashes if non paragraph item is given as caption * 2418: time formats no longer allowed in today_fmt * 2395: Sphinx crashes if unicode character in image filename * 2396: "too many values to unpack" in genindex-single * 2405: numref link in PDF jumps to the wrong location * 2414: missing number in PDF hyperlinks to code listings * 2440: wrong import for gmtime.
Upgrade to version 1.3.4. OK'd by maintainer markd@.
Use ALTERNATIVES framework to allow concurrent installation under multiple pythons. Bump PKGREVISION.
Update to 1.2.3: Release 1.2.3 (released Sep 1, 2014) ==================================== Features added -------------- * #1518: `sphinx-apidoc` command now have a `--version` option to show version information and exit * New locales: Hebrew, European Portuguese, Vietnamese. Bugs fixed ---------- * #636: Keep straight single quotes in literal blocks in the LaTeX build. * #1419: Generated i18n sphinx.js files are missing message catalog entries from '.js_t' and '.html'. The issue was introduced from Sphinx-1.1 * #1363: Fix i18n: missing python domain's cross-references with currentmodule directive or currentclass directive. * #1444: autosummary does not create the description from attributes docstring. * #1457: In python3 environment, make linkcheck cause "Can't convert 'bytes' object to str implicitly" error when link target url has a hash part. Thanks to Jorge_C. * #1467: Exception on Python3 if nonexistent method is specified by automethod * #1441: autosummary can't handle nested classes correctly. * #1499: With non-callable `setup` in a conf.py, now sphinx-build emits user-friendly error message. * #1502: In autodoc, fix display of parameter defaults containing backslashes. * #1226: autodoc, autosummary: importing setup.py by automodule will invoke setup process and execute `sys.exit()`. Now sphinx avoids SystemExit exception and emits warnings without unexpected termination. * #1503: py:function directive generate incorrectly signature when specifying a default parameter with an empty list `[]`. Thanks to Geert Jansen. * #1508: Non-ASCII filename raise exception on make singlehtml, latex, man, texinfo and changes. * #1531: On Python3 environment, docutils.conf with 'source_link=true' in the general section cause type error. * PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses with inheritance-diagram directive. Thanks to WAKAYAMA shirou. * PR#281, PR#282, #1509: TODO extension not compatible with websupport. Thanks to Takeshi Komiya. * #1477: gettext does not extract nodes.line in a table or list. * #1544: `make text` generate wrong table when it has empty table cells. * #1522: Footnotes from table get displayed twice in LaTeX. This problem has been appeared from Sphinx-1.2.1 by #949. * #508: Sphinx every time exit with zero when is invoked from setup.py command. ex. `python setup.py build_sphinx -b doctest` return zero even if doctest failed.
Update to 1.2.1:
Release 1.2.1 (released Jan 19, 2014)
=====================================
Bugs fixed
----------
* #1335: Fix autosummary template overloading with exclamation prefix like
``{% extends "!autosummary/class.rst" %}`` cause infinite recursive function
call. This was caused by PR#181.
* #1337: Fix autodoc with ``autoclass_content="both"`` uses useless
``object.__init__`` docstring when class does not have ``__init__``.
This was caused by a change for #1138.
* #1340: Can't search alphabetical words on the HTML quick search generated
with language='ja'.
* #1319: Do not crash if the :confval:`html_logo` file does not exist.
* #603: Do not use the HTML-ized title for building the search index (that
resulted in "literal" being found on every page with a literal in the
title).
* #751: Allow production lists longer than a page in LaTeX by using longtable.
* #764: Always look for stopwords lowercased in JS search.
* #814: autodoc: Guard against strange type objects that don't have
``__bases__``.
* #932: autodoc: Do not crash if ``__doc__`` is not a string.
* #933: Do not crash if an :rst:role:`option` value is malformed (contains
spaces but no option name).
* #908: On Python 3, handle error messages from LaTeX correctly in the pngmath
extension.
* #943: In autosummary, recognize "first sentences" to pull from the docstring
if they contain uppercase letters.
* #923: Take the entire LaTeX document into account when caching
pngmath-generated images. This rebuilds them correctly when
:confval:`pngmath_latex_preamble` changes.
* #901: Emit a warning when using docutils' new "math" markup without a Sphinx
math extension active.
* #845: In code blocks, when the selected lexer fails, display line numbers
nevertheless if configured.
* #929: Support parsed-literal blocks in LaTeX output correctly.
* #949: Update the tabulary.sty packed with Sphinx.
* #1050: Add anonymous labels into ``objects.inv`` to be referenced via
:mod:`~sphinx.ext.intersphinx`.
* #1095: Fix print-media stylesheet being included always in the "scrolls"
theme.
* #1085: Fix current classname not getting set if class description has
``:noindex:`` set.
* #1181: Report option errors in autodoc directives more gracefully.
* #1155: Fix autodocumenting C-defined methods as attributes in Python 3.
* #1233: Allow finding both Python classes and exceptions with the "class" and
"exc" roles in intersphinx.
* #1198: Allow "image" for the "figwidth" option of the :rst:dir:`figure`
directive as documented by docutils.
* #1152: Fix pycode parsing errors of Python 3 code by including two grammar
versions for Python 2 and 3, and loading the appropriate version for the
running Python version.
* #1017: Be helpful and tell the user when the argument to :rst:dir:`option`
does not match the required format.
* #1345: Fix two bugs with :confval:`nitpick_ignore`; now you don't have to
remove the store environment for changes to have effect.
* #1072: In the JS search, fix issues searching for upper-cased words by
lowercasing words before stemming.
* #1299: Make behavior of the :rst:dir:`math` directive more consistent and
avoid producing empty environments in LaTeX output.
* #1308: Strip HTML tags from the content of "raw" nodes before feeding it
to the search indexer.
* #1249: Fix duplicate LaTeX page numbering for manual documents.
* #1292: In the linkchecker, retry HEAD requests when denied by HTTP 405.
Also make the redirect code apparent and tweak the output a bit to be
more obvious.
* #1285: Avoid name clashes between C domain objects and section titles.
* #848: Always take the newest code in incremental rebuilds with the
:mod:`sphinx.ext.viewcode` extension.
* #979, #1266: Fix exclude handling in ``sphinx-apidoc``.
* #1302: Fix regression in :mod:`sphinx.ext.inheritance_diagram` when
documenting classes that can't be pickled.
* #1316: Remove hard-coded ``font-face`` resources from epub theme.
* #1329: Fix traceback with empty translation msgstr in .po files.
* #1300: Fix references not working in translated documents in some instances.
* #1283: Fix a bug in the detection of changed files that would try to access
doctrees of deleted documents.
* #1330: Fix :confval:`exclude_patterns` behavior with subdirectories in the
:confval:`html_static_path`.
* #1323: Fix emitting empty ``<ul>`` tags in the HTML writer, which is not
valid HTML.
* #1147: Don't emit a sidebar search box in the "singlehtml" builder.
Documentation
-------------
* #1325: Added a "Intersphinx" tutorial section. (:file:`doc/tutorial.rst`)
Update to 1.2:
Release 1.2 (released Dec 10, 2013)
===================================
Features added
--------------
* Added ``sphinx.version_info`` tuple for programmatic checking of the Sphinx
version.
Incompatible changes
--------------------
* Removed the ``sphinx.ext.refcounting`` extension -- it is very specific to
CPython and has no place in the main distribution.
Bugs fixed
----------
* Restore ``versionmodified`` CSS class for versionadded/changed and deprecated
directives.
* Fix: `html_theme_path=['.']` is a trigger of rebuild all documents always
(This change keeps the current "theme changes cause a rebuild" feature).
* #1296: Fix invalid charset in HTML help generated HTML files for default
locale.
* PR#190: Fix gettext does not extract figure caption and rubric title inside
other blocks. Thanks to Michael Schlenker.
* PR#176: Make sure setup_command test can always import Sphinx. Thanks to
Dmitry Shachnev.
* #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
* #1269: Fix ResourceWarnings with Python 3.2 or later.
* #1138: Fix: When ``autodoc_docstring_signature = True`` and
``autoclass_content = 'init'`` or ``'both'``, __init__ line should be
removed from class documentation.
Release 1.2 beta3 (released Oct 3, 2013)
========================================
Features added
--------------
* The Sphinx error log files will now include a list of the loaded extensions
for help in debugging.
Incompatible changes
--------------------
* PR#154: Remove "sphinx" prefix from LaTeX class name except 'sphinxmanual'
and 'sphinxhowto'. Now you can use your custom document class without
'sphinx' prefix. Thanks to Erik B.
Bugs fixed
----------
* #1265: Fix i18n: crash when translating a section name that is pointed to from
a named target.
* A wrong condition broke the search feature on first page that is usually
index.rst. This issue was introduced in 1.2b1.
* #703: When Sphinx can't decode filenames with non-ASCII characters, Sphinx now
catches UnicodeError and will continue if possible instead of raising the
exception.
Release 1.2 beta2 (released Sep 17, 2013)
=========================================
Features added
--------------
* ``apidoc`` now ignores "_private" modules by default, and has an option ``-P``
to include them.
* ``apidoc`` now has an option to not generate headings for packages and
modules, for the case that the module docstring already includes a reST
heading.
* PR#161: ``apidoc`` can now write each module to a standalone page instead of
combining all modules in a package on one page.
* Builders: rebuild i18n target document when catalog updated.
* Support docutils.conf 'writers' and 'html4css1 writer' section in the HTML
writer. The latex, manpage and texinfo writers also support their respective
'writers' sections.
* The new :confval:`html_extra_path` config value allows to specify directories
with files that should be copied directly to the HTML output directory.
* Autodoc directives for module data and attributes now support an
``annotation`` option, so that the default display of the data/attribute
value can be overridden.
* PR#136: Autodoc directives now support an ``imported-members`` option to
include members imported from different modules.
* New locales: Macedonian, Sinhala, Indonesian.
* Theme package collection by using setuptools plugin mechanism.
Incompatible changes
--------------------
* PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Creation-Date
that was generated by gettext builder. Thanks to masklinn and Jakub Wilk.
Bugs fixed
----------
* PR#132: Updated jQuery version to 1.8.3.
* PR#141, #982: Avoid crash when writing PNG file using Python 3. Thanks to
Marcin Wojdyr.
* PR#145: In parallel builds, sphinx drops second document file to write.
Thanks to tychoish.
* PR#151: Some styling updates to tables in LaTeX.
* PR#153: The "extensions" config value can now be overridden.
* PR#155: Added support for some C++11 function qualifiers.
* Fix: 'make gettext' caused UnicodeDecodeError when templates contain utf-8
encoded strings.
* #828: use inspect.getfullargspec() to be able to document functions with
keyword-only arguments on Python 3.
* #1090: Fix i18n: multiple cross references (term, ref, doc) in the same line
return the same link.
* #1157: Combination of 'globaltoc.html' and hidden toctree caused exception.
* #1159: fix wrong generation of objects inventory for Python modules, and
add a workaround in intersphinx to fix handling of affected inventories.
* #1160: Citation target missing caused an AssertionError.
* #1162, PR#139: singlehtml builder didn't copy images to _images/.
* #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexander Dupuy.
* #1185: Don't crash when a Python module has a wrong or no encoding declared,
and non-ASCII characters are included.
* #1188: sphinx-quickstart raises UnicodeEncodeError if "Project version"
includes non-ASCII characters.
* #1189: "Title underline is too short" WARNING is given when using fullwidth
characters to "Project name" on quickstart.
* #1190: Output TeX/texinfo/man filename has no basename (only extension)
when using non-ASCII characters in the "Project name" on quickstart.
* #1192: Fix escaping problem for hyperlinks in the manpage writer.
* #1193: Fix i18n: multiple link references in the same line return the same
link.
* #1176: Fix i18n: footnote reference number missing for auto numbered named
footnote and auto symbol footnote.
* PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to tychoish.
* #1204: Fix wrong generation of links to local intersphinx targets.
* #1206: Fix i18n: gettext did not translate admonition directive's title.
* #1232: Sphinx generated broken ePub files on Windows.
* #1259: Guard the debug output call when emitting events; to prevent the
repr() implementation of arbitrary objects causing build failures.
* #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
* #1234: Ignoring the string consists only of white-space characters.
Release 1.2 beta1 (released Mar 31, 2013)
=========================================
Incompatible changes
--------------------
* Removed ``sphinx.util.compat.directive_dwim()`` and
``sphinx.roles.xfileref_role()`` which were deprecated since version 1.0.
* PR#122: the files given in :confval:`latex_additional_files` now override TeX
files included by Sphinx, such as ``sphinx.sty``.
* PR#124: the node generated by :rst:dir:`versionadded`,
:rst:dir:`versionchanged` and :rst:dir:`deprecated` directives now includes
all added markup (such as "New in version X") as child nodes, and no
additional text must be generated by writers.
* PR#99: the :rst:dir:`seealso` directive now generates admonition nodes instead
of the custom ``seealso`` node.
Features added
--------------
* Markup
- The :rst:dir:`toctree` directive and the ``toctree()`` template function now
have an ``includehidden`` option that includes hidden toctree entries (bugs
#790 and #1047). A bug in the ``maxdepth`` option for the ``toctree()``
template function has been fixed (bug #1046).
- PR#99: Strip down seealso directives to normal admonitions. This removes
their unusual CSS classes (admonition-see-also), inconsistent LaTeX
admonition title ("See Also" instead of "See also"), and spurious indentation
in the text builder.
* HTML builder
- #783: Create a link to full size image if it is scaled with width or height.
- #1067: Improve the ordering of the JavaScript search results: matches in titles
come before matches in full text, and object results are better categorized.
Also implement a pluggable search scorer.
- #1053: The "rightsidebar" and "collapsiblesidebar" HTML theme options now work
together.
- Update to jQuery 1.7.1 and Underscore.js 1.3.1.
* Texinfo builder
- An "Index" node is no longer added when there are no entries.
- "deffn" categories are no longer capitalized if they contain capital
letters.
- ``desc_annotation`` nodes are now rendered.
- ``strong`` and ``emphasis`` nodes are now formatted like
``literal``\s. The reason for this is because the standard Texinfo markup
(``*strong*`` and ``_emphasis_``) resulted in confusing output due to the
common usage of using these constructs for documenting parameter names.
- Field lists formatting has been tweaked to better display
"Info field lists".
- ``system_message`` and ``problematic`` nodes are now formatted in a similar
fashion as done by the text builder.
- "en-dash" and "em-dash" conversion of hyphens is no longer performed in
option directive signatures.
- ``@ref`` is now used instead of ``@pxref`` for cross-references which
prevents the word "see" from being added before the link (does not affect
the Info output).
- The ``@finalout`` command has been added for better TeX output.
- ``transition`` nodes are now formatted using underscores ("_") instead of
asterisks ("*").
- The default value for the ``paragraphindent`` has been changed from 2 to 0
meaning that paragraphs are no longer indented by default.
- #1110: A new configuration value :confval:`texinfo_no_detailmenu` has been
added for controlling whether a ``@detailmenu`` is added in the "Top"
node's menu.
- Detailed menus are no longer created except for the "Top" node.
- Fixed an issue where duplicate domain indices would result in invalid
output.
* LaTeX builder:
- PR#115: Add ``'transition'`` item in :confval:`latex_elements` for
customizing how transitions are displayed. Thanks to Jeff Klukas.
- PR#114: The LaTeX writer now includes the "cmap" package by default. The
``'cmappkg'`` item in :confval:`latex_elements` can be used to control this.
Thanks to Dmitry Shachnev.
- The ``'fontpkg'`` item in :confval:`latex_elements` now defaults to ``''``
when the :confval:`language` uses the Cyrillic script. Suggested by Dmitry
Shachnev.
- The :confval:`latex_documents`, :confval:`texinfo_documents`, and
:confval:`man_pages` configuration values will be set to default values based
on the :confval:`master_doc` if not explicitly set in :file:`conf.py`.
Previously, if these values were not set, no output would be genereted by
their respective builders.
* Internationalization:
- Add i18n capabilities for custom templates. For example: The Sphinx
reference documentation in doc directory provides a ``sphinx.pot`` file with
message strings from ``doc/_templates/*.html`` when using ``make gettext``.
* Other builders:
- Added the Docutils-native XML and pseudo-XML builders. See
:class:`XMLBuilder` and :class:`PseudoXMLBuilder`.
- PR#45: The linkcheck builder now checks ``#anchor``\ s for existence.
- PR#123, #1106: Add :confval:`epub_use_index` configuration value. If
provided, it will be used instead of :confval:`html_use_index` for epub
builder.
- PR#126: Add :confval:`epub_tocscope` configuration value. The setting
controls the generation of the epub toc. The user can now also include
hidden toc entries.
- PR#112: Add :confval:`epub_show_urls` configuration value.
* Extensions:
- PR#52: ``special_members`` flag to autodoc now behaves like ``members``.
- PR#47: Added :mod:`sphinx.ext.linkcode` extension.
- PR#25: In inheritance diagrams, the first line of the class docstring
is now the tooltip for the class.
* Command-line interfaces:
- PR#75: Added ``--follow-links`` option to sphinx-apidoc.
- #869: sphinx-build now has the option :option:`-T` for printing the full
traceback after an unhandled exception.
- sphinx-build now supports the standard :option:`--help` and
:option:`--version` options.
- sphinx-build now provides more specific error messages when called with
invalid options or arguments.
- sphinx-build now has a verbose option :option:`-v` which can be repeated for
greater effect. A single occurrance provides a slightly more verbose output
than normal. Two or more occurrences of this option provides more detailed
output which may be useful for debugging.
* Locales:
- PR#74: Fix some Russian translation.
- PR#54: Added Norwegian bokmaal translation.
- PR#35: Added Slovak translation.
- PR#28: Added Hungarian translation.
- #1113: Add Hebrew locale.
- #1097: Add Basque locale.
- #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
- #1012: Update Estonian translation.
* Optimizations:
- Speed up building the search index by caching the results of the word
stemming routines. Saves about 20 seconds when building the Python
documentation.
- PR#108: Add experimental support for parallel building with a new
:option:`-j` option.
Documentation
-------------
* PR#88: Added the "Sphinx Developer's Guide" (:file:`doc/devguide.rst`)
which outlines the basic development process of the Sphinx project.
* Added a detailed "Installing Sphinx" document (:file:`doc/install.rst`).
Bugs fixed
----------
* PR#124: Fix paragraphs in versionmodified are ignored when it has no
dangling paragraphs. Fix wrong html output (nested ``<p>`` tag). Fix
versionmodified is not translatable. Thanks to Nozomu Kaneko.
* PR#111: Respect add_autodoc_attrgetter() even when inherited-members is set.
Thanks to A. Jesse Jiryu Davis.
* PR#97: Fix footnote handling in translated documents.
* Fix text writer not handling visit_legend for figure directive contents.
* Fix text builder not respecting wide/fullwidth characters: title underline
width, table layout width and text wrap width.
* Fix leading space in LaTeX table header cells.
* #1132: Fix LaTeX table output for multi-row cells in the first column.
* #1128: Fix Unicode errors when trying to format time strings with a
non-standard locale.
* #1127: Fix traceback when autodoc tries to tokenize a non-Python file.
* #1126: Fix double-hyphen to en-dash conversion in wrong places such as
command-line option names in LaTeX.
* #1123: Allow whitespaces in filenames given to :rst:dir:`literalinclude`.
* #1120: Added improvements about i18n for themes "basic", "haiku" and
"scrolls" that Sphinx built-in. Thanks to Leonardo J. Caballero G.
* #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero G.
* #1117: Handle .pyx files in sphinx-apidoc.
* #1112: Avoid duplicate download files when referenced from documents in
different ways (absolute/relative).
* #1111: Fix failure to find uppercase words in search when
:confval:`html_search_language` is 'ja'. Thanks to Tomo Saito.
* #1108: The text writer now correctly numbers enumerated lists with
non-default start values (based on patch by Ewan Edwards).
* #1102: Support multi-context "with" statements in autodoc.
* #1090: Fix gettext not extracting glossary terms.
* #1074: Add environment version info to the generated search index to avoid
compatibility issues with old builds.
* #1070: Avoid un-pickling issues when running Python 3 and the saved
environment was created under Python 2.
* #1069: Fixed error caused when autodoc would try to format signatures of
"partial" functions without keyword arguments (patch by Artur Gaspar).
* #1062: sphinx.ext.autodoc use __init__ method signature for class signature.
* #1055: Fix web support with relative path to source directory.
* #1043: Fix sphinx-quickstart asking again for yes/no questions because
``input()`` returns values with an extra '\r' on Python 3.2.0 +
Windows. Thanks to Régis Décamps.
* #1041: Fix failure of the cpp domain parser to parse a const type with a
modifier.
* #1038: Fix failure of the cpp domain parser to parse C+11 "static constexpr"
declarations. Thanks to Jakub Wilk.
* #1029: Fix intersphinx_mapping values not being stable if the mapping has
plural key/value set with Python 3.3.
* #1028: Fix line block output in the text builder.
* #1024: Improve Makefile/make.bat error message if Sphinx is not found. Thanks
to Anatoly Techtonik.
* #1018: Fix "container" directive handling in the text builder.
* #1015: Stop overriding jQuery contains() in the JavaScript.
* #1010: Make pngmath images transparent by default; IE7+ should handle it.
* #1008: Fix test failures with Python 3.3.
* #995: Fix table-of-contents and page numbering for the LaTeX "howto" class.
* #976: Fix gettext does not extract index entries.
* PR#72: #975: Fix gettext not extracting definition terms before docutils 0.10.
* #961: Fix LaTeX output for triple quotes in code snippets.
* #958: Do not preserve ``environment.pickle`` after a failed build.
* #955: Fix i18n transformation.
* #940: Fix gettext does not extract figure caption.
* #920: Fix PIL packaging issue that allowed to import ``Image`` without PIL
namespace. Thanks to Marc Schlaich.
* #723: Fix the search function on local files in WebKit based browsers.
* #440: Fix coarse timestamp resolution in some filesystem generating a wrong
list of outdated files.
Changes 1.1.2: * 809: Include custom fixers in the source distribution. Changes 1.1.1: * 791: Fix QtHelp, DevHelp and HtmlHelp index entry links. * 792: Include "sphinx-apidoc" in the source distribution. * 797: Don't crash on a misformatted glossary. * 801: Make intersphinx work properly without SSL support. * 805: Make the ``Sphinx.add_index_to_domain`` method work correctly. * 780: Fix Python 2.5 compatibility.
PLIST fix
Update py-sphinx to 1.0.1
* Support for domains has been added. A domain is a collection of
directives and roles that all describe objects belonging together,
e.g. elements of a programming language. A few builtin domains are
provided:
- Python
- C
- C++
- JavaScript
- reStructuredText
* The old markup for defining and linking to C directives is now
deprecated. It will not work anymore in future versions without
activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx
1.0, it is activated by default.
* Removed support for old dependency versions; requirements are now:
- docutils >= 0.5
- Jinja2 >= 2.2
* Removed deprecated elements:
- ``exclude_dirs`` config value
- ``sphinx.builder`` module
Features added
--------------
* General:
- Added a "nitpicky" mode that emits warnings for all missing
references. It is activated by the :option:`-n` command-line switch
or the :confval:`nitpicky` config value.
- Added ``latexpdf`` target in quickstart Makefile.
* Markup:
- The :rst:role:`menuselection` and :rst:role:`guilabel` roles now
support ampersand accelerators.
- New more compact doc field syntax is now recognized: ``:param type
name: description``.
- Added ``tab-width`` option to :rst:dir:`literalinclude` directive.
- Added ``titlesonly`` option to :rst:dir:`toctree` directive.
- Added the ``prepend`` and ``append`` options to the
:rst:dir:`literalinclude` directive.
- #284: All docinfo metadata is now put into the document metadata, not
just the author.
- The :rst:role:`ref` role can now also reference tables by caption.
- The :rst:dir:`include` directive now supports absolute paths, which
are interpreted as relative to the source directory.
- In the Python domain, references like ``:func:`.name``` now look for
matching names with any prefix if no direct match is found.
* New builders:
- Added a builder for the Epub format.
- Added a builder for manual pages.
- Added a single-file HTML builder.
* Extensions:
- Added the :mod:`~sphinx.ext.viewcode` extension.
- Added the :mod:`~sphinx.ext.extlinks` extension.
- Added support for source ordering of members in autodoc, with
``autodoc_member_order = 'bysource'``.
- Added :confval:`autodoc_default_flags` config value, which can be
used to select default flags for all autodoc directives.
- Added a way for intersphinx to refer to named labels in other
projects, and to specify the project you want to link to.
- #280: Autodoc can now document instance attributes assigned in
``__init__`` methods.
- Many improvements and fixes to the :mod:`~sphinx.ext.autosummary`
extension, thanks to Pauli Virtanen.
- #309: The :mod:`~sphinx.ext.graphviz` extension can now output SVG
instead of PNG images, controlled by the
:confval:`graphviz_output_format` config value.
- Added ``alt`` option to :rst:dir:`graphviz` extension directives.
- Added ``exclude`` argument to :func:`.autodoc.between`.
Update to Sphinx-0.6.6 many bug fixes.
Update to sphinx 0.6.2
* Incompatible changes:
- Templating now requires the Jinja2 library
- The "document" div tag has been moved out of the ``layout.html``
template's "document" block
- The ``autodoc_skip_member`` event now also gets to decide
whether to skip members whose name starts with underscores.
* Theming support
* Markup:
- Due to popular demand, added a ``:doc:`` role which directly
links to another document without the need of creating a
label to which a ``:ref:`` could link to.
- Added a ``:download:`` role that marks a non-document file
for inclusion into the HTML output and links to it.
- Added an ``only`` directive that can selectively include text
based on enabled "tags".
- Added HTML section numbers, enabled by giving a
``:numbered:`` flag to the ``toctree`` directive.
- Scaled images now get a link to the unscaled version.
- SVG images are now supported in HTML (via ``<object>`` and
``<embed>`` tags).
* Builders:
- New builder for Qt help collections, by Antonio Valentino.
- The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates
a separate directory for every page, and places the page there
in a file called ``index.html``.
* New translations:
* Bug Fixes.
Remove @dirrm entries from PLISTs
Import py-sphinx 0.5.1 Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of multiple reStructuredText sources), written by Georg Brandl. It was originally created to translate the new Python documentation, but has now been cleaned up in the hope that it will be useful to many other projects. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils. Although it is still under constant development, the following features are already present, work fine and can be seen "in action" in the Python docs: * Output formats: HTML (including Windows HTML Help), plain text and LaTeX, for printable PDF versions * Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information * Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children * Automatic indices: general index as well as a module index * Code handling: automatic highlighting using the Pygments highlighter * Various extensions are available, e.g. for automatic testing of snippets and inclusion of appropriately formatted docstrings.
Initial revision