diff --git a/CHANGES b/CHANGES index ade0ffdaa..1b7f015cd 100644 --- a/CHANGES +++ b/CHANGES @@ -21,16 +21,12 @@ Bugs fixed Testing -------- -Release 5.2.0 (in development) +Release 5.3.0 (in development) ============================== Dependencies ------------ -* #10356: Sphinx now uses declarative metadata with ``pyproject.toml`` to - create packages, using PyPA's ``build`` project as a build backend. Patch by - Adam Turner. - Incompatible changes -------------------- @@ -40,6 +36,47 @@ Deprecated Features added -------------- +Bugs fixed +---------- + +Testing +-------- + +Release 5.2.1 (released Sep 24, 2022) +===================================== + +Bugs fixed +---------- + +* #10861: 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 +------------ + +* #10356: 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 +---------- + +* #10843: Support for HTML 4 output. Patch by Adam Turner. + +Features added +-------------- + +* #10738: napoleon: Add support for docstring types using 'of', like + ``type of type``. Example: ``tuple of int``. * #10286: C++, support requires clauses not just between the template parameter lists and the declaration. * #10755: linkcheck: Check the source URL of raw directives that use the ``url`` @@ -53,44 +90,18 @@ Features added * #6692: HTML Search: Include explicit :rst:dir:`index` directive index entries in the search index and search results. Patch by Adam Turner * #10816: imgmath: Allow embedding images in HTML as base64 - -Bugs fixed ----------- - -* #10257: C++, ensure consistent non-specialization template argument - representation. -* #10729: C++, fix parsing of certain non-type template parameter packs. -* #10715: Revert #10520: "Fix" use of sidebar classes in ``agogo.css_t`` - -Testing --------- - -Release 5.1.2 (in development) -============================== - -Dependencies ------------- - -Incompatible changes --------------------- - -Deprecated ----------- - -Features added --------------- - -* #10738: napoleon: Add support for docstring types using 'of', like - ``type of type``. Example: ``tuple of int``. +* #10854: HTML Search: Use browser localstorage for highlight control, stop + storing highlight parameters in URL query strings. Patch by Adam Turner. Bugs fixed ---------- * #10723: LaTeX: 5.1.0 has made the 'sphinxsetup' ``verbatimwithframe=false`` become without effect. - -Testing --------- +* #10257: C++, ensure consistent non-specialization template argument + representation. +* #10729: C++, fix parsing of certain non-type template parameter packs. +* #10715: Revert #10520: "Fix" use of sidebar classes in ``agogo.css_t`` Release 5.1.1 (released Jul 26, 2022) ===================================== diff --git a/doc/changes.rst b/doc/changes.rst index 3fe902404..96853fe09 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -11,5 +11,12 @@ Changelog .. raw:: latex \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}% + \makeatletter + \addtocontents{toc}% + {\def\string\l@section{\string\@dottedtocline{1}{1.5em}{3.3em}}} + \addtocontents{toc}% + {\def\string\l@subsection{\string\@dottedtocline{2}{4.8em}{4em}}} + \makeatother + .. include:: ../CHANGES diff --git a/doc/conf.py b/doc/conf.py index 58e8e6c27..f903fd570 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -48,6 +48,7 @@ epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'), ('develop.xhtml', 'Sphinx development')] epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', '_static/searchtools.js', + '_static/sphinx_highlight.js', '_static/basic.css', '_static/language_data.js', 'search.html', '_static/websupport.js'] diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 18b0e6d04..8c850ceb6 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -22,6 +22,11 @@ The following is a list of deprecated interfaces. - (will be) Removed - Alternatives + * - HTML 4 support + - 5.2 + - 7.0 + - N/A + * - ``sphinx.util.path_stabilize`` - 5.1 - 7.0 diff --git a/doc/latex.rst b/doc/latex.rst index 84dd2e433..7fa90fe89 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1300,6 +1300,12 @@ Macros ``\sphinxtableofcontentshook``. This macro is also executed by the ``'howto'`` docclass, but defaults to empty with it. + .. hint:: + + If adding to preamble the loading of ``tocloft`` package, also add to + preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset + ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization. + - ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'`` :confval:`latex_elements` key. Defined in the class files :file:`sphinxmanual.cls` and diff --git a/karma.conf.js b/karma.conf.js index 082584cf7..8a18e80ba 100644 --- a/karma.conf.js +++ b/karma.conf.js @@ -15,8 +15,10 @@ module.exports = function(config) { // list of files / patterns to load in the browser files: [ + 'tests/js/documentation_options.js', 'sphinx/themes/basic/static/doctools.js', 'sphinx/themes/basic/static/searchtools.js', + 'sphinx/themes/basic/static/sphinx_highlight.js', 'tests/js/*.js' ], diff --git a/pyproject.toml b/pyproject.toml index 0119c99b8..8321a3310 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -150,6 +150,7 @@ show_error_context = true strict_optional = true warn_redundant_casts = true warn_unused_ignores = true +disallow_any_generics = true [[tool.mypy.overrides]] module = [ @@ -181,6 +182,30 @@ module = [ ] strict_optional = false +[[tool.mypy.overrides]] +module = [ + "sphinx.application", + "sphinx.builders.*", + "sphinx.cmd.*", + "sphinx.config", + "sphinx.deprecation", + "sphinx.domains.*", + "sphinx.environment.*", + "sphinx.events", + "sphinx.ext.*", + "sphinx.highlighting", + "sphinx.jinja2glue", + "sphinx.locale", + "sphinx.pycode.*", + "sphinx.registry", + "sphinx.roles", + "sphinx.search.*", + "sphinx.testing.*", + "sphinx.util.*", + "sphinx.writers.*", +] +disallow_any_generics = false + [tool.pytest.ini_options] filterwarnings = [ "all", diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index e23f570d7..e22ce5fa2 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -1,4 +1,4 @@ -"""Additional docutils nodes.""" +"""Document tree nodes that Sphinx defines on top of those in Docutils.""" from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence @@ -119,7 +119,7 @@ class toctree(nodes.General, nodes.Element, translatable): ############################################################# class _desc_classes_injector(nodes.Element, not_smartquotable): - """Helper base class for injecting a fixes list of classes. + """Helper base class for injecting a fixed list of classes. Use as the first base class. """ @@ -390,7 +390,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement): class centered(nodes.Part, nodes.TextElement): - """Deprecated.""" + """This node is deprecated.""" class acks(nodes.Element): @@ -455,13 +455,18 @@ class pending_xref(nodes.Inline, nodes.Element): class pending_xref_condition(nodes.Inline, nodes.TextElement): - """Node for cross-references that are used to choose appropriate - content of the reference by conditions on the resolving phase. + """Node representing a potential way to create a cross-reference and the + condition in which this way should be used. - When the :py:class:`pending_xref` node contains one or more - **pending_xref_condition** nodes, the cross-reference resolver - should choose the content of the reference using defined conditions - in ``condition`` attribute of each pending_xref_condition nodes:: + This node is only allowed to be placed under a :py:class:`pending_xref` + node. A **pending_xref** node must contain either no **pending_xref_condition** + nodes or it must only contains **pending_xref_condition** nodes. + + The cross-reference resolver will replace a :py:class:`pending_xref` which + contains **pending_xref_condition** nodes by the content of exactly one of + those **pending_xref_condition** nodes' content. It uses the **condition** + attribute to decide which **pending_xref_condition** node's content to + use. For example, let us consider how the cross-reference resolver acts on:: @@ -471,32 +476,26 @@ class pending_xref_condition(nodes.Inline, nodes.TextElement): io.StringIO - After the processing of cross-reference resolver, one of the content node - under pending_xref_condition node is chosen by its condition and to be - removed all of pending_xref_condition nodes:: + If the cross-reference resolver successfully resolves the cross-reference, + then it rewrites the **pending_xref** as:: - # When resolved the cross-reference successfully StringIO - # When resolution is failed + Otherwise, if the cross-reference resolution failed, it rewrites the + **pending_xref** as:: + io.StringIO - .. note:: This node is only allowed to be placed under pending_xref node. - It is not allows to place it under other nodes. In addition, - pending_xref node must contain only pending_xref_condition - nodes if it contains one or more pending_xref_condition nodes. - - The pending_xref_condition node should have **condition** attribute. + The **pending_xref_condition** node should have **condition** attribute. Domains can be store their individual conditions into the attribute to filter contents on resolving phase. As a reserved condition name, ``condition="*"`` is used for the fallback of resolution failure. Additionally, as a recommended condition name, ``condition="resolved"`` - is used for the representation of resolstion success in the intersphinx - module. + represents a resolution success in the intersphinx module. .. versionadded:: 4.0 """ diff --git a/sphinx/application.py b/sphinx/application.py index 254678569..8a349ee48 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -636,8 +636,9 @@ class Sphinx: :param name: The name of the directive :param cls: A directive class - :param override: If true, install the directive forcedly even if another directive + :param override: If false, do not install it if another directive is already installed as the same name + If true, unconditionally install the directive. For example, a custom directive named ``my-directive`` would be added like this: @@ -684,8 +685,9 @@ class Sphinx: :param name: The name of role :param role: A role function - :param override: If true, install the role forcedly even if another role is already - installed as the same name + :param override: If false, do not install it if another role + is already installed as the same name + If true, unconditionally install the role. For more details about role functions, see `the Docutils docs `__ . @@ -705,8 +707,9 @@ class Sphinx: Register a Docutils role that does nothing but wrap its contents in the node given by *nodeclass*. - If *override* is True, the given *nodeclass* is forcedly installed even if - a role named as *name* is already installed. + :param override: If false, do not install it if another role + is already installed as the same name + If true, unconditionally install the role. .. versionadded:: 0.6 .. versionchanged:: 1.8 @@ -725,8 +728,9 @@ class Sphinx: """Register a domain. :param domain: A domain class - :param override: If true, install the domain forcedly even if another domain + :param override: If false, do not install it if another domain is already installed as the same name + If true, unconditionally install the domain. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -744,8 +748,9 @@ class Sphinx: :param domain: The name of target domain :param name: A name of directive :param cls: A directive class - :param override: If true, install the directive forcedly even if another directive + :param override: If false, do not install it if another directive is already installed as the same name + If true, unconditionally install the directive. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -763,8 +768,9 @@ class Sphinx: :param domain: The name of the target domain :param name: The name of the role :param role: The role function - :param override: If true, install the role forcedly even if another role is already - installed as the same name + :param override: If false, do not install it if another role + is already installed as the same name + If true, unconditionally install the role. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -780,8 +786,9 @@ class Sphinx: :param domain: The name of the target domain :param index: The index class - :param override: If true, install the index forcedly even if another index is - already installed as the same name + :param override: If false, do not install it if another index + is already installed as the same name + If true, unconditionally install the index. .. versionadded:: 1.0 .. versionchanged:: 1.8 @@ -886,8 +893,10 @@ class Sphinx: (Of course, the element following the ``topic`` directive needn't be a section.) - If *override* is True, the given crossref_type is forcedly installed even if - a crossref_type having the same name is already installed. + + :param override: If false, do not install it if another cross-reference type + is already installed as the same name + If true, unconditionally install the cross-reference type. .. versionchanged:: 1.8 Add *override* keyword. @@ -946,20 +955,22 @@ class Sphinx: loading_method: Optional[str] = None, **kwargs: Any) -> None: """Register a JavaScript file to include in the HTML output. - :param filename: The filename of the JavaScript file. It must be relative to the HTML - static path, a full URI with scheme, or ``None`` value. The ``None`` - value is used to create inline ``