Sphinx 7.1.2__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/themes/basic/static/searchtools.js

@@ -57,12 +57,12 @@ const _removeChildren = (element) => {
 const _escapeRegExp = (string) =>
   string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
 
-const _displayItem = (item, searchTerms) => {
+const _displayItem = (item, searchTerms, highlightTerms) => {
   const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
-  const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT;
   const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
   const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
   const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
+  const contentRoot = document.documentElement.dataset.content_root;
 
   const [docName, title, anchor, descr, score, _filename] = item;
 
@@ -75,20 +75,24 @@ const _displayItem = (item, searchTerms) => {
     if (dirname.match(/\/index\/$/))
       dirname = dirname.substring(0, dirname.length - 6);
     else if (dirname === "index/") dirname = "";
-    requestUrl = docUrlRoot + dirname;
+    requestUrl = contentRoot + dirname;
     linkUrl = requestUrl;
   } else {
     // normal html builders
-    requestUrl = docUrlRoot + docName + docFileSuffix;
+    requestUrl = contentRoot + docName + docFileSuffix;
     linkUrl = docName + docLinkSuffix;
   }
   let linkEl = listItem.appendChild(document.createElement("a"));
   linkEl.href = linkUrl + anchor;
   linkEl.dataset.score = score;
   linkEl.innerHTML = title;
-  if (descr)
+  if (descr) {
     listItem.appendChild(document.createElement("span")).innerHTML =
       " (" + descr + ")";
+    // highlight search terms in the description
+    if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
+      highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
+  }
   else if (showSearchSummary)
     fetch(requestUrl)
       .then((responseData) => responseData.text())
@@ -97,6 +101,9 @@ const _displayItem = (item, searchTerms) => {
           listItem.appendChild(
             Search.makeSearchSummary(data, searchTerms)
           );
+        // highlight search terms in the summary
+        if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
+          highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
       });
   Search.output.appendChild(listItem);
 };
@@ -115,14 +122,15 @@ const _finishSearch = (resultCount) => {
 const _displayNextItem = (
   results,
   resultCount,
-  searchTerms
+  searchTerms,
+  highlightTerms,
 ) => {
   // results left, load the summary and display it
   // this is intended to be dynamic (don't sub resultsCount)
   if (results.length) {
-    _displayItem(results.pop(), searchTerms);
+    _displayItem(results.pop(), searchTerms, highlightTerms);
     setTimeout(
-      () => _displayNextItem(results, resultCount, searchTerms),
+      () => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
       5
     );
   }
@@ -360,7 +368,7 @@ const Search = {
     // console.info("search results:", Search.lastresults);
 
     // print the results
-    _displayNextItem(results, results.length, searchTerms);
+    _displayNextItem(results, results.length, searchTerms, highlightTerms);
   },
 
   /**

sphinx/themes/basic/static/sphinx_highlight.js

@@ -29,14 +29,19 @@ const _highlight = (node, addItems, text, className) => {
       }
 
       span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+      const rest = document.createTextNode(val.substr(pos + text.length));
       parent.insertBefore(
         span,
         parent.insertBefore(
-          document.createTextNode(val.substr(pos + text.length)),
+          rest,
           node.nextSibling
         )
       );
       node.nodeValue = val.substr(0, pos);
+      /* There may be more occurrences of search term in this node. So call this
+       * function recursively on the remaining fragment.
+       */
+      _highlight(rest, addItems, text, className);
 
       if (isInSVG) {
         const rect = document.createElementNS(
@@ -140,5 +145,10 @@ const SphinxHighlight = {
   },
 };
 
-_ready(SphinxHighlight.highlightSearchWords);
-_ready(SphinxHighlight.initEscapeListener);
+_ready(() => {
+  /* Do not call highlightSearchWords() when we are on the search page.
+   * It will highlight words from the *previous* search query.
+   */
+  if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
+  SphinxHighlight.initEscapeListener();
+});

sphinx/themes/bizstyle/static/bizstyle.css_t

@@ -181,6 +181,10 @@ a:hover {
     text-decoration: underline;
 }
 
+a:visited {
+    color: #551a8b;
+}
+
 div.body a {
     text-decoration: underline;
 }

sphinx/themes/classic/theme.conf

@@ -24,7 +24,7 @@ headbgcolor      = #f2f2f2
 headtextcolor    = #20435c
 headlinkcolor    = #c60f0f
 linkcolor        = #355f7c
-visitedlinkcolor = #355f7c
+visitedlinkcolor = #551a8b
 codebgcolor      = unset
 codetextcolor    = unset
 

sphinx/themes/epub/static/epub.css_t

@@ -26,11 +26,16 @@ div.clearer {
     clear: both;
 }
 
-a:link, a:visited {
+a:link {
     color: #3333ff;
     text-decoration: underline;
 }
 
+a:visited {
+    color: #551a8b;
+    text-decoration: underline;
+} 
+
 img {
     border: 0;
     max-width: 100%;

sphinx/themes/haiku/theme.conf

@@ -10,5 +10,5 @@ body_max_width    = 70em
 textcolor         = #333333
 headingcolor      = #0c3762
 linkcolor         = #dc3c01
-visitedlinkcolor  = #892601
+visitedlinkcolor  = #551a8b
 hoverlinkcolor    = #ff4500

sphinx/themes/nature/static/nature.css_t

@@ -142,6 +142,10 @@ a:hover {
     text-decoration: underline;
 }
 
+a:visited {
+    color: #551A8B;
+}
+
 div.body h1,
 div.body h2,
 div.body h3,

sphinx/themes/nonav/static/nonav.css_t

@@ -15,11 +15,16 @@ div.clearer {
     clear: both;
 }
 
-a:link, a:visited {
+a:link {
     color: #3333ff;
     text-decoration: underline;
 }
 
+a:visited {
+    color: #551a8b;
+    text-decoration: underline;
+}
+
 img {
     border: 0;
     max-width: 100%;

sphinx/themes/pyramid/static/pyramid.css_t

@@ -181,6 +181,10 @@ a:hover, a:hover .pre {
     text-decoration: underline;
 }
 
+a:visited {
+    color: #551a8b;
+}
+
 div.body h1,
 div.body h2,
 div.body h3,

sphinx/themes/scrolls/static/scrolls.css_t

@@ -187,6 +187,10 @@ a:hover {
     color: {{ theme_visitedlinkcolor }};
 }
 
+a:visited {
+    color: {{ theme_visitedlinkcolor }};
+}
+
 pre {
     background-image: url(metal.png);
     border-top: 1px solid #ccc;

sphinx/themes/scrolls/theme.conf

@@ -9,5 +9,5 @@ body_max_width = 680
 headerbordercolor = #1752b4
 subheadlinecolor  = #0d306b
 linkcolor         = #1752b4
-visitedlinkcolor  = #444
+visitedlinkcolor  = #551a8b
 admonitioncolor   = #28437f

sphinx/themes/sphinxdoc/static/sphinxdoc.css_t

@@ -151,6 +151,10 @@ a:hover {
     color: #2491CF;
 }
 
+a:visited {
+    color: #551A8B;
+}
+
 div.body a {
     text-decoration: underline;
 }

sphinx/theming.py

@@ -16,6 +16,8 @@ if sys.version_info >= (3, 10):
 else:
     from importlib_metadata import entry_points
 
+import contextlib
+
 from sphinx import package_dir
 from sphinx.errors import ThemeError
 from sphinx.locale import __
@@ -107,17 +109,18 @@ class Theme:
                                     'searched theme configs') % (section, name)) from exc
             return default
 
-    def get_options(self, overrides: dict[str, Any] = {}) -> dict[str, Any]:
+    def get_options(self, overrides: dict[str, Any] | None = None) -> dict[str, Any]:
         """Return a dictionary of theme options and their values."""
+        if overrides is None:
+            overrides = {}
+
         if self.base:
             options = self.base.get_options()
         else:
             options = {}
 
-        try:
+        with contextlib.suppress(configparser.NoSectionError):
             options.update(self.config.items('options'))
-        except configparser.NoSectionError:
-            pass
 
         for option, value in overrides.items():
             if option not in options:
@@ -130,10 +133,9 @@ class Theme:
     def cleanup(self) -> None:
         """Remove temporary directories."""
         if self.rootdir:
-            try:
+            with contextlib.suppress(Exception):
                 shutil.rmtree(self.rootdir)
-            except Exception:
-                pass
+
         if self.base:
             self.base.cleanup()
 

sphinx/transforms/__init__.py

@@ -4,10 +4,9 @@ from __future__ import annotations
 
 import re
 import unicodedata
-from typing import TYPE_CHECKING, Any, Generator, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Node, Text
 from docutils.transforms import Transform, Transformer
 from docutils.transforms.parts import ContentsFilter
 from docutils.transforms.universal import SmartQuotes
@@ -15,7 +14,6 @@ from docutils.utils import normalize_language_tag
 from docutils.utils.smartquotes import smartchars
 
 from sphinx import addnodes
-from sphinx.config import Config
 from sphinx.locale import _, __
 from sphinx.util import logging
 from sphinx.util.docutils import new_document
@@ -23,7 +21,12 @@ from sphinx.util.i18n import format_date
 from sphinx.util.nodes import apply_source_workaround, is_smartquotable
 
 if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from docutils.nodes import Node, Text
+
     from sphinx.application import Sphinx
+    from sphinx.config import Config
     from sphinx.domains.std import StandardDomain
     from sphinx.environment import BuildEnvironment
 
@@ -412,6 +415,78 @@ class GlossarySorter(SphinxTransform):
                 )
 
 
+class ReorderConsecutiveTargetAndIndexNodes(SphinxTransform):
+    """Index nodes interspersed between target nodes prevent other
+    Transformations from combining those target nodes,
+    e.g. ``PropagateTargets``.  This transformation reorders them:
+
+    Given the following ``document`` as input::
+
+        <document>
+            <target ids="id1" ...>
+            <index entries="...1...">
+            <target ids="id2" ...>
+            <target ids="id3" ...>
+            <index entries="...2...">
+            <target ids="id4" ...>
+
+    The transformed result will be::
+
+        <document>
+            <index entries="...1...">
+            <index entries="...2...">
+            <target ids="id1" ...>
+            <target ids="id2" ...>
+            <target ids="id3" ...>
+            <target ids="id4" ...>
+    """
+
+    # This transform MUST run before ``PropagateTargets``.
+    default_priority = 220
+
+    def apply(self, **kwargs: Any) -> None:
+        for target in self.document.findall(nodes.target):
+            _reorder_index_target_nodes(target)
+
+
+def _reorder_index_target_nodes(start_node: nodes.target) -> None:
+    """Sort target and index nodes.
+
+    Find all consecutive target and index nodes starting from ``start_node``,
+    and move all index nodes to before the first target node.
+    """
+    nodes_to_reorder: list[nodes.target | addnodes.index] = []
+
+    # Note that we cannot use 'condition' to filter,
+    # as we want *consecutive* target & index nodes.
+    node: nodes.Node
+    for node in start_node.findall(descend=False, siblings=True):
+        if isinstance(node, (nodes.target, addnodes.index)):
+            nodes_to_reorder.append(node)
+            continue
+        break  # must be a consecutive run of target or index nodes
+
+    if len(nodes_to_reorder) < 2:
+        return  # Nothing to reorder
+
+    parent = nodes_to_reorder[0].parent
+    if parent == nodes_to_reorder[-1].parent:
+        first_idx = parent.index(nodes_to_reorder[0])
+        last_idx = parent.index(nodes_to_reorder[-1])
+        if first_idx + len(nodes_to_reorder) - 1 == last_idx:
+            parent[first_idx:last_idx + 1] = sorted(nodes_to_reorder, key=_sort_key)
+
+
+def _sort_key(node: nodes.Node) -> int:
+    # Must be a stable sort.
+    if isinstance(node, addnodes.index):
+        return 0
+    if isinstance(node, nodes.target):
+        return 1
+    msg = f'_sort_key called with unexpected node type {type(node)!r}'
+    raise ValueError(msg)
+
+
 def setup(app: Sphinx) -> dict[str, Any]:
     app.add_transform(ApplySourceWorkaround)
     app.add_transform(ExtraTranslatableNodes)
@@ -428,6 +503,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_transform(DoctreeReadEvent)
     app.add_transform(ManpageLink)
     app.add_transform(GlossarySorter)
+    app.add_transform(ReorderConsecutiveTargetAndIndexNodes)
 
     return {
         'version': 'builtin',

sphinx/transforms/compact_bullet_list.py

@@ -2,15 +2,18 @@
 
 from __future__ import annotations
 
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
-from docutils.nodes import Node
 
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.transforms import SphinxTransform
 
+if TYPE_CHECKING:
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 
 class RefOnlyListChecker(nodes.GenericNodeVisitor):
     """Raise `nodes.NodeFound` if non-simple list item is encountered.

sphinx/transforms/i18n.py

@@ -6,20 +6,20 @@ import contextlib
 from os import path
 from re import DOTALL, match
 from textwrap import indent
-from typing import TYPE_CHECKING, Any, Sequence, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from docutils import nodes
 from docutils.io import StringInput
 
 from sphinx import addnodes
-from sphinx.config import Config
 from sphinx.domains.std import make_glossary_term, split_term_classifiers
 from sphinx.errors import ConfigError
 from sphinx.locale import __
 from sphinx.locale import init as init_locale
 from sphinx.transforms import SphinxTransform
-from sphinx.util import get_filetype, logging, split_index_msg
+from sphinx.util import get_filetype, logging
 from sphinx.util.i18n import docname_to_domain
+from sphinx.util.index_entries import split_index_msg
 from sphinx.util.nodes import (
     IMAGE_TYPE_NODES,
     LITERAL_TYPE_NODES,
@@ -29,7 +29,10 @@ from sphinx.util.nodes import (
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from sphinx.application import Sphinx
+    from sphinx.config import Config
 
 
 logger = logging.getLogger(__name__)
@@ -311,7 +314,8 @@ class _NodeUpdater:
                 return (
                     node["refdomain"],
                     node["reftype"],
-                    node['reftarget'],)
+                    node['reftarget'],
+                )
 
         for old in old_xrefs:
             key = get_ref_key(old)
@@ -350,9 +354,16 @@ class Locale(SphinxTransform):
         if not has_catalog:
             return
 
+        catalogues = [getattr(catalog, '_catalog', None)]
+        while (catalog := catalog._fallback) is not None:  # type: ignore[attr-defined]
+            catalogues.append(getattr(catalog, '_catalog', None))
+        merged: dict[str, str] = {}
+        for catalogue in filter(None, reversed(catalogues)):  # type: dict[str, str]
+            merged |= catalogue
+
         # phase1: replace reference ids with translated names
         for node, msg in extract_messages(self.document):
-            msgstr = catalog.gettext(msg)
+            msgstr = merged.get(msg, '')
 
             # There is no point in having #noqa on literal blocks because
             # they cannot contain references.  Recognizing it would just
@@ -361,10 +372,14 @@ class Locale(SphinxTransform):
             if not isinstance(node, LITERAL_TYPE_NODES):
                 msgstr, _ = parse_noqa(msgstr)
 
-            if not msgstr or msgstr == msg or not msgstr.strip():
+            if msgstr.strip() == '':
                 # as-of-yet untranslated
                 node['translated'] = False
                 continue
+            if msgstr == msg:
+                # identical source and translated messages
+                node['translated'] = True
+                continue
 
             # Avoid "Literal block expected; none found." warnings.
             # If msgstr ends with '::' then it cause warning message at
@@ -413,7 +428,7 @@ class Locale(SphinxTransform):
             if node.setdefault('translated', False):  # to avoid double translation
                 continue  # skip if the node is already translated by phase1
 
-            msgstr = catalog.gettext(msg)
+            msgstr = merged.get(msg, '')
             noqa = False
 
             # See above.
@@ -507,7 +522,7 @@ class Locale(SphinxTransform):
                     msg_parts = split_index_msg(entry_type, value)
                     msgstr_parts = []
                     for part in msg_parts:
-                        msgstr = catalog.gettext(part)
+                        msgstr = merged.get(part, '')
                         if not msgstr:
                             msgstr = part
                         msgstr_parts.append(msgstr)
@@ -565,8 +580,9 @@ class AddTranslationClasses(SphinxTransform):
             add_translated = False
             add_untranslated = True
         else:
-            raise ConfigError('translation_progress_classes must be'
-                              ' True, False, "translated" or "untranslated"')
+            msg = ('translation_progress_classes must be '
+                   'True, False, "translated" or "untranslated"')
+            raise ConfigError(msg)
 
         for node in self.document.findall(NodeMatcher(translated=Any)):  # type: nodes.Element
             if node['translated']:

sphinx/transforms/post_transforms/__init__.py

@@ -3,15 +3,12 @@
 from __future__ import annotations
 
 import re
-from typing import Any, Sequence, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
 
 from sphinx import addnodes
-from sphinx.addnodes import pending_xref
-from sphinx.application import Sphinx
-from sphinx.domains import Domain
 from sphinx.errors import NoUri
 from sphinx.locale import __
 from sphinx.transforms import SphinxTransform
@@ -19,6 +16,13 @@ from sphinx.util import logging
 from sphinx.util.docutils import SphinxTranslator
 from sphinx.util.nodes import find_pending_xref_condition, process_only_nodes
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sphinx.addnodes import pending_xref
+    from sphinx.application import Sphinx
+    from sphinx.domains import Domain
+
 logger = logging.getLogger(__name__)
 
 
@@ -246,18 +250,27 @@ class SigElementFallbackTransform(SphinxPostTransform):
             # subclass of SphinxTranslator supports desc_sig_element nodes automatically.
             return
 
-        # for the leaf elements (desc_sig_element), the translator should support _all_
-        if not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS):
+        # for the leaf elements (desc_sig_element), the translator should support _all_,
+        # unless there exists a generic visit_desc_sig_element default visitor
+        if (not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS)
+                and not has_visitor(translator, addnodes.desc_sig_element)):
             self.fallback(addnodes.desc_sig_element)
 
         if not has_visitor(translator, addnodes.desc_inline):
             self.fallback(addnodes.desc_inline)
 
-    def fallback(self, nodeType: Any) -> None:
-        for node in self.document.findall(nodeType):
+    def fallback(self, node_type: Any) -> None:
+        """Translate nodes of type *node_type* to docutils inline nodes.
+
+        The original node type name is stored as a string in a private
+        ``_sig_node_type`` attribute if the latter did not exist.
+        """
+        for node in self.document.findall(node_type):
             newnode = nodes.inline()
             newnode.update_all_atts(node)
             newnode.extend(node)
+            # Only set _sig_node_type if not defined by the user
+            newnode.setdefault('_sig_node_type', node.tagname)
             node.replace_self(newnode)
 
 

sphinx/transforms/post_transforms/code.py

@@ -3,17 +3,20 @@
 from __future__ import annotations
 
 import sys
-from typing import Any, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from docutils import nodes
-from docutils.nodes import Node, TextElement
 from pygments.lexers import PythonConsoleLexer, guess_lexer
 
 from sphinx import addnodes
-from sphinx.application import Sphinx
 from sphinx.ext import doctest
 from sphinx.transforms import SphinxTransform
 
+if TYPE_CHECKING:
+    from docutils.nodes import Node, TextElement
+
+    from sphinx.application import Sphinx
+
 
 class HighlightSetting(NamedTuple):
     language: str