Merge branch 'master' into issue-13096/html-search-handle-proto-query

AUTHORS.rst

@@ -18,8 +18,11 @@ Contributors
 
 *Listed alphabetically in forename, surname order*
 
+* Aaron Carlisle -- basic theme and templating improvements
+* Adam Dangoor -- improved static typing
 * Adrián Chaves (Gallaecio) -- coverage builder improvements
 * Alastair Houghton -- Apple Help builder
+* Alex Gaynor -- linkcheck retry on errors
 * Alexander Todorov -- inheritance_diagram tests and improvements
 * Andi Albrecht -- agogo theme
 * Antonio Valentino -- qthelp builder, docstring inheritance
@@ -28,17 +31,25 @@ Contributors
 * Ben Egan -- Napoleon improvements
 * Benjamin Peterson -- unittests
 * Blaise Laflamme -- pyramid theme
+* Brecht Machiels -- builder entry-points
 * Bruce Mitchener -- Minor epub improvement
 * Buck Evan -- dummy builder
 * Charles Duffy -- original graphviz extension
+* Chris Holdgraf -- improved documentation structure
 * Chris Lamb -- reproducibility fixes
 * Christopher Perkins -- autosummary integration
 * Dan MacKinlay -- metadata fixes
 * Daniel Bültmann -- todo extension
+* Daniel Eades -- improved static typing
+* Daniel Hahler -- testing and CI improvements
 * Daniel Pizetta -- inheritance diagram improvements
 * Dave Kuhlman -- original LaTeX writer
+* Dimitri Papadopoulos Orfanos -- linting and spelling
+* Dmitry Shachnev -- modernisation and reproducibility
 * Doug Hellmann -- graphviz improvements
+* Eric Larson -- better error messages
 * Eric N. Vander Weele -- autodoc improvements
+* Eric Wieser -- autodoc improvements
 * Etienne Desautels -- apidoc module
 * Ezio Melotti -- collapsible sidebar JavaScript
 * Filip Vavera -- napoleon todo directive
@@ -53,25 +64,34 @@ Contributors
 * Jacob Mason -- websupport library (GSOC project)
 * James Addison -- linkcheck and HTML search improvements
 * Jeppe Pihl -- literalinclude improvements
+* Jeremy Maitin-Shepard -- C++ domain improvements
 * Joel Wurtz -- cellspanning support in LaTeX
 * John Waltman -- Texinfo builder
+* Jon Dufresne -- modernisation
 * Josip Dzolonga -- coverage builder
+* Juan Luis Cano Rodríguez -- new tutorial (2021)
 * Julien Palard -- Colspan and rowspan in text builder
+* Justus Magin -- napoleon improvements
 * Kevin Dunn -- MathJax extension
 * KINEBUCHI Tomohiko -- typing Sphinx as well as docutils
 * Kurt McKee -- documentation updates
 * Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
+* Louis Maddox -- better docstrings
 * Łukasz Langa -- partial support for autodoc
 * Marco Buttu -- doctest extension (pyversion option)
 * Martin Hans -- autodoc improvements
 * Martin Larralde -- additional napoleon admonitions
+* Martin Liška -- option directive and role improvements
 * Martin Mahner -- nature theme
 * Matthew Fernandez -- todo extension fix
 * Matthew Woodcraft -- text output improvements
+* Matthias Geier -- style improvements
 * Michael Droettboom -- inheritance_diagram extension
 * Michael Wilson -- Intersphinx HTTP basic auth support
 * Nathan Damon -- bugfix in validation of static paths in html builders
+* Nils Kattenbeck -- pygments dark style
 * Pauli Virtanen -- autodoc improvements, autosummary extension
+* Rafael Fontenelle -- internationalisation
 * \A. Rafey Khan -- improved intersphinx typing
 * Roland Meister -- epub builder
 * Sebastian Wiesner -- image handling, distutils support

CHANGES.rst

@@ -12,6 +12,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* #13037: Deprecate the ``SingleHTMLBuilder.fix_refuris`` method.
+  Patch by James Addison.
+
 Features added
 --------------
 

doc/_static/diagrams/sphinx_build_phases.dot

@@ -0,0 +1,18 @@
+digraph phases {
+
+    graph [
+        rankdir = LR
+    ]
+
+    node [
+        shape = rect;
+        style = filled;
+        fillcolor ="#f7f7f7";
+        fontcolor = "#0a507a"
+    ]
+
+    Initialization -> Reading;
+    Reading -> "Consistency checks";
+    "Consistency checks" -> Resolving;
+    Resolving -> Writing;
+}

doc/extdev/appapi.rst

@@ -95,6 +95,8 @@ package.
 
 .. automethod:: Sphinx.is_parallel_allowed
 
+.. automethod:: Sphinx.set_html_assets_policy
+
 .. exception:: ExtensionError
 
    All these methods raise this exception if something went wrong with the

doc/extdev/deprecated.rst

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - Removed
      - Alternatives
 
+   * - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder.fix_refuris``
+     - 8.2
+     - 10.0
+     - N/A
+
    * - ``sphinx.util.FilenameUniqDict``
      - 8.1
      - 10.0

doc/extdev/index.rst

@@ -95,6 +95,9 @@ Build phases
 One thing that is vital in order to understand extension mechanisms is the way
 in which a Sphinx project is built: this works in several phases.
 
+.. graphviz:: /_static/diagrams/sphinx_build_phases.dot
+   :caption: Build phases
+
 **Phase 0: Initialization**
 
 In this phase, almost nothing of interest to us happens.  The source

doc/usage/extensions/doctest.rst

@@ -51,6 +51,14 @@ a comma-separated list of group names.
    A setup code block.  This code is not shown in the output for other builders,
    but executed before the doctests of the group(s) it belongs to.
 
+   .. rubric:: Options
+
+   .. rst:directive:option:: skipif: condition
+      :type: text
+
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipping tests conditionally <doctest-skipif>`.
+
 
 .. rst:directive:: .. testcleanup:: [group]
 
@@ -59,6 +67,14 @@ a comma-separated list of group names.
 
    .. versionadded:: 1.1
 
+   .. rubric:: Options
+
+   .. rst:directive:option:: skipif: condition
+      :type: text
+
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipping tests conditionally <doctest-skipif>`.
+
 
 .. rst:directive:: .. doctest:: [group]
 
@@ -67,72 +83,99 @@ a comma-separated list of group names.
    default set of flags is specified by the :confval:`doctest_default_flags`
    configuration variable.
 
-   This directive supports five options:
+   .. rubric:: Options
+
+   .. rst:directive:option:: hide
+
+     Hide the doctest block in other builders.
+     By default it is shown as a highlighted doctest block.
+
+   .. rst:directive:option:: options: doctest flags
+      :type: comma separated list
+
+      A comma-separated list of doctest flags that apply to each example in the
+      tests.  (You still can give explicit flags per example, with doctest comments,
+      but they will show up in other builders too.)
+
+      Alternatively, you can give inline doctest options, like in doctest:
+
+      .. code-block:: pycon
 
-   * ``hide``, a flag option, hides the doctest block in other builders.  By
-     default it is shown as a highlighted doctest block.
+         >>> datetime.date.now()   # doctest: +SKIP
+         datetime.date(2008, 1, 1)
 
-   * ``options``, a string option, can be used to give a comma-separated list of
-     doctest flags that apply to each example in the tests.  (You still can give
-     explicit flags per example, with doctest comments, but they will show up in
-     other builders too.)
+      They will be respected when the test is run, but by default will be stripped from
+      presentation output. You can prevent stripping using the option
+      :rst:dir:`doctest:no-trim-doctest-flags`.
 
-   * ``pyversion``, a string option, can be used to specify the required Python
-     version for the example to be tested. For instance, in the following case
-     the example will be tested only for Python versions greater than 3.12::
+   .. rst:directive:option:: pyversion
+      :type: text
+
+      Specify the required Python version for the example to be tested. For instance,
+      in the following case the example will be tested only for Python versions greater
+      than 3.12::
 
          .. doctest::
             :pyversion: > 3.12
 
-     The following operands are supported:
-
-     * ``~=``: Compatible release clause
-     * ``==``: Version matching clause
-     * ``!=``: Version exclusion clause
-     * ``<=``, ``>=``: Inclusive ordered comparison clause
-     * ``<``, ``>``: Exclusive ordered comparison clause
-     * ``===``: Arbitrary equality clause.
+      The following operands are supported:
 
-     ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
-     <440#version-specifiers>`.
+      * ``~=``: Compatible release clause
+      * ``==``: Version matching clause
+      * ``!=``: Version exclusion clause
+      * ``<=``, ``>=``: Inclusive ordered comparison clause
+      * ``<``, ``>``: Exclusive ordered comparison clause
+      * ``===``: Arbitrary equality clause.
 
-     .. versionadded:: 1.6
+      ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
+      <440#version-specifiers>`.
 
-     .. versionchanged:: 1.7
+      .. versionadded:: 1.6
 
-        Supported PEP-440 operands and notations
+      .. versionchanged:: 1.7
 
-   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
-     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
-     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
-     individually.  Default is ``trim-doctest-flags``.
+         Supported PEP-440 operands and notations
 
-   Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
-   signal a blank line in the expected output.  The ``<BLANKLINE>`` is removed
-   when building presentation output (HTML, LaTeX etc.).
+   .. rst:directive:option:: trim-doctest-flags
+                             no-trim-doctest-flags
 
-   Also, you can give inline doctest options, like in doctest::
+      Whether to trim remove doctest flags (comments looking like
+      ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers
+      individually.  Default is ``trim-doctest-flags``.
 
-      >>> datetime.date.now()   # doctest: +SKIP
-      datetime.date(2008, 1, 1)
+      Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
+      signal a blank line in the expected output.  The ``<BLANKLINE>`` is removed
+      when building presentation output (HTML, LaTeX etc.).
 
-   They will be respected when the test is run, but stripped from presentation
-   output.
+   .. rst:directive:option:: skipif: condition
+      :type: text
 
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipping tests conditionally <doctest-skipif>`.
 
 .. rst:directive:: .. testcode:: [group]
 
    A code block for a code-output-style test.
 
-   This directive supports three options:
+   .. rubric:: Options
+
+   .. rst:directive:option:: hide
+
+      Hide the code block in other builders.
+      By default it is shown as a highlighted code block.
+
+   .. rst:directive:option:: trim-doctest-flags
+                             no-trim-doctest-flags
+
+      Whether to trim remove doctest flags (comments looking like
+      ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers
+      individually.  Default is ``trim-doctest-flags``.
 
-   * ``hide``, a flag option, hides the code block in other builders.  By
-     default it is shown as a highlighted code block.
+   .. rst:directive:option:: skipif: condition
+      :type: text
 
-   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
-     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
-     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
-     individually.  Default is ``trim-doctest-flags``.
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipping tests conditionally <doctest-skipif>`.
 
    .. note::
 
@@ -159,18 +202,28 @@ a comma-separated list of group names.
    The corresponding output, or the exception message, for the last
    :rst:dir:`testcode` block.
 
-   This directive supports four options:
+   .. rst:directive:option:: hide
 
-   * ``hide``, a flag option, hides the output block in other builders.  By
-     default it is shown as a literal block without highlighting.
+     Hide the doctest block in other builders.
+     By default it is shown as a highlighted doctest block.
 
-   * ``options``, a string option, can be used to give doctest flags
-     (comma-separated) just like in normal doctest blocks.
+   .. rst:directive:option:: options: doctest flags
+      :type: comma separated list
 
-   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
-     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
-     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
-     individually.  Default is ``trim-doctest-flags``.
+      A comma-separated list of doctest flags.
+
+   .. rst:directive:option:: trim-doctest-flags
+                             no-trim-doctest-flags
+
+      Whether to trim remove doctest flags (comments looking like
+      ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers
+      individually.  Default is ``trim-doctest-flags``.
+
+   .. rst:directive:option:: skipif: condition
+      :type: text
+
+      Skip the directive if the python expression *condition* is True.
+      See :ref:`skipping tests conditionally <doctest-skipif>`.
 
    Example::
 
@@ -217,6 +270,8 @@ The following is an example for the usage of the directives.  The test via
       This parrot wouldn't voom if you put 3000 volts through it!
 
 
+.. _doctest-skipif:
+
 Skipping tests conditionally
 ----------------------------
 

sphinx/builders/epub3.py

@@ -65,7 +65,7 @@ class NavPoint(NamedTuple):
     '|[\ufdf0-\ufffd]|[\U00010000-\U000effff]'
 )
 _xml_name_char = (
-    _xml_name_start_char + r'\-|\.' '|[0-9]|\u00b7|[\u0300-\u036f]|[\u203f-\u2040]'
+    _xml_name_start_char + r'\-|\.|[0-9]|\u00b7|[\u0300-\u036f]|[\u203f-\u2040]'
 )
 _XML_NAME_PATTERN = re.compile(f'({_xml_name_start_char})({_xml_name_char})*')