Sphinx 8.0.1__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/transforms/__init__.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any, cast
 from docutils import nodes
 from docutils.transforms import Transform, Transformer
 from docutils.transforms.parts import ContentsFilter
+from docutils.transforms.references import Footnotes
 from docutils.transforms.universal import SmartQuotes
 from docutils.utils import normalize_language_tag
 from docutils.utils.smartquotes import smartchars
@@ -119,7 +120,9 @@ class DefaultSubstitutions(SphinxTransform):
             if (name := ref['refname']) in to_handle:
                 ref.replace_self(self._handle_default_substitution(name))
 
-    def _handle_default_substitution(self, name: _DEFAULT_SUBSTITUTION_NAMES) -> nodes.Text:
+    def _handle_default_substitution(
+        self, name: _DEFAULT_SUBSTITUTION_NAMES
+    ) -> nodes.Text:
         if name == 'translation progress':
             # special handling: calculate translation progress
             return nodes.Text(_calculate_translation_progress(self.document))
@@ -127,10 +130,8 @@ class DefaultSubstitutions(SphinxTransform):
             if text := self.config.today:
                 return nodes.Text(text)
             # special handling: can also specify a strftime format
-            return nodes.Text(format_date(
-                self.config.today_fmt or _('%b %d, %Y'),
-                language=self.config.language,
-            ))
+            today_fmt = self.config.today_fmt or _('%b %d, %Y')
+            return nodes.Text(format_date(today_fmt, language=self.config.language))
         # config.version and config.release
         return nodes.Text(getattr(self.config, name))
 
@@ -184,8 +185,7 @@ class HandleCodeBlocks(SphinxTransform):
     def apply(self, **kwargs: Any) -> None:
         # move doctest blocks out of blockquotes
         for node in self.document.findall(nodes.block_quote):
-            if all(isinstance(child, nodes.doctest_block) for child
-                   in node.children):
+            if all(isinstance(child, nodes.doctest_block) for child in node.children):
                 node.replace_self(node.children)
         # combine successive doctest blocks
         # for node in self.document.findall(nodes.doctest_block):
@@ -207,12 +207,14 @@ class AutoNumbering(SphinxTransform):
     default_priority = 210
 
     def apply(self, **kwargs: Any) -> None:
-        domain: StandardDomain = self.env.domains['std']
+        domain: StandardDomain = self.env.domains.standard_domain
 
         for node in self.document.findall(nodes.Element):
-            if (domain.is_enumerable_node(node) and
-                    domain.get_numfig_title(node) is not None and
-                    node['ids'] == []):
+            if (
+                domain.is_enumerable_node(node)
+                and domain.get_numfig_title(node) is not None
+                and node['ids'] == []
+            ):
                 self.document.note_implicit_target(node)
 
 
@@ -246,7 +248,7 @@ class ApplySourceWorkaround(SphinxTransform):
     default_priority = 10
 
     def apply(self, **kwargs: Any) -> None:
-        for node in self.document.findall():  # type: Node
+        for node in self.document.findall():
             if isinstance(node, nodes.TextElement | nodes.image | nodes.topic):
                 apply_source_workaround(node)
 
@@ -261,8 +263,13 @@ class AutoIndexUpgrader(SphinxTransform):
     def apply(self, **kwargs: Any) -> None:
         for node in self.document.findall(addnodes.index):
             if 'entries' in node and any(len(entry) == 4 for entry in node['entries']):
-                msg = __('4 column based index found. '
-                         'It might be a bug of extensions you use: %r') % node['entries']
+                msg = (
+                    __(
+                        '4 column based index found. '
+                        'It might be a bug of extensions you use: %r'
+                    )
+                    % node['entries']
+                )
                 logger.warning(msg, location=node)
                 for i, entry in enumerate(node['entries']):
                     if len(entry) == 4:
@@ -294,23 +301,40 @@ class UnreferencedFootnotesDetector(SphinxTransform):
     Detect unreferenced footnotes and emit warnings
     """
 
-    default_priority = 200
+    default_priority = Footnotes.default_priority + 2
 
     def apply(self, **kwargs: Any) -> None:
         for node in self.document.footnotes:
-            if node['names'] == []:
-                # footnote having duplicated number.  It is already warned at parser.
-                pass
-            elif node['names'][0] not in self.document.footnote_refs:
-                logger.warning(__('Footnote [%s] is not referenced.'), node['names'][0],
-                               type='ref', subtype='footnote',
-                               location=node)
-
+            # note we do not warn on duplicate footnotes here
+            # (i.e. where the name has been moved to dupnames)
+            # since this is already reported by docutils
+            if not node['backrefs'] and node['names']:
+                logger.warning(
+                    __('Footnote [%s] is not referenced.'),
+                    node['names'][0] if node['names'] else node['dupnames'][0],
+                    type='ref',
+                    subtype='footnote',
+                    location=node,
+                )
+        for node in self.document.symbol_footnotes:
+            if not node['backrefs']:
+                logger.warning(
+                    __('Footnote [*] is not referenced.'),
+                    type='ref',
+                    subtype='footnote',
+                    location=node,
+                )
         for node in self.document.autofootnotes:
-            if not any(ref['auto'] == node['auto'] for ref in self.document.autofootnote_refs):
-                logger.warning(__('Footnote [#] is not referenced.'),
-                               type='ref', subtype='footnote',
-                               location=node)
+            # note we do not warn on duplicate footnotes here
+            # (i.e. where the name has been moved to dupnames)
+            # since this is already reported by docutils
+            if not node['backrefs'] and node['names']:
+                logger.warning(
+                    __('Footnote [#] is not referenced.'),
+                    type='ref',
+                    subtype='footnote',
+                    location=node,
+                )
 
 
 class DoctestTransform(SphinxTransform):
@@ -385,10 +409,7 @@ class SphinxSmartQuotes(SmartQuotes, SphinxTransform):
 
         # confirm selected language supports smart_quotes or not
         language = self.env.settings['language_code']
-        return any(
-            tag in smartchars.quotes
-            for tag in normalize_language_tag(language)
-        )
+        return any(tag in smartchars.quotes for tag in normalize_language_tag(language))
 
     def get_tokens(self, txtnodes: list[Text]) -> Iterator[tuple[str, str]]:
         # A generator that yields ``(texttype, nodetext)`` tuples for a list
@@ -421,13 +442,13 @@ class GlossarySorter(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         for glossary in self.document.findall(addnodes.glossary):
-            if glossary["sorted"]:
+            if glossary['sorted']:
                 definition_list = cast(nodes.definition_list, glossary[0])
                 definition_list[:] = sorted(
                     definition_list,
                     key=lambda item: unicodedata.normalize(
-                        'NFD',
-                        cast(nodes.term, item)[0].astext().lower()),
+                        'NFD', cast(nodes.term, item)[0].astext().lower()
+                    ),
                 )
 
 
@@ -490,7 +511,7 @@ def _reorder_index_target_nodes(start_node: nodes.target) -> None:
         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)
+            parent[first_idx : last_idx + 1] = sorted(nodes_to_reorder, key=_sort_key)
 
 
 def _sort_key(node: nodes.Node) -> int:

sphinx/transforms/compact_bullet_list.py

@@ -30,8 +30,9 @@ class RefOnlyListChecker(nodes.GenericNodeVisitor):
         pass
 
     def visit_list_item(self, node: nodes.list_item) -> None:
-        children: list[Node] = [child for child in node.children
-                                if not isinstance(child, nodes.Invisible)]
+        children: list[Node] = [
+            child for child in node.children if not isinstance(child, nodes.Invisible)
+        ]
         if len(children) != 1:
             raise nodes.NodeFound
         if not isinstance(children[0], nodes.paragraph):

sphinx/transforms/i18n.py

@@ -48,8 +48,14 @@ EXCLUDED_PENDING_XREF_ATTRIBUTES = ('refexplicit',)
 N = TypeVar('N', bound=nodes.Node)
 
 
-def publish_msgstr(app: Sphinx, source: str, source_path: str, source_line: int,
-                   config: Config, settings: Any) -> nodes.Element:
+def publish_msgstr(
+    app: Sphinx,
+    source: str,
+    source_path: str,
+    source_line: int,
+    config: Config,
+    settings: Any,
+) -> nodes.Element:
     """Publish msgstr (single line) into docutils document
 
     :param sphinx.application.Sphinx app: sphinx application
@@ -67,13 +73,15 @@ def publish_msgstr(app: Sphinx, source: str, source_path: str, source_line: int,
         config.rst_prolog = None
 
         from sphinx.io import SphinxI18nReader
+
         reader = SphinxI18nReader()
         reader.setup(app)
         filetype = get_filetype(config.source_suffix, source_path)
         parser = app.registry.create_source_parser(app, filetype)
         doc = reader.read(
-            source=StringInput(source=source,
-                               source_path=f"{source_path}:{source_line}:<translated>"),
+            source=StringInput(
+                source=source, source_path=f'{source_path}:{source_line}:<translated>'
+            ),
             parser=parser,
             settings=settings,
         )
@@ -85,7 +93,7 @@ def publish_msgstr(app: Sphinx, source: str, source_path: str, source_line: int,
 
 
 def parse_noqa(source: str) -> tuple[str, bool]:
-    m = match(r"(.*)(?<!\\)#\s*noqa\s*$", source, DOTALL)
+    m = match(r'(.*)(?<!\\)#\s*noqa\s*$', source, DOTALL)
     if m:
         return m.group(1), True
     else:
@@ -108,29 +116,43 @@ class _NodeUpdater:
     """Contains logic for updating one node with the translated content."""
 
     def __init__(
-        self, node: nodes.Element, patch: nodes.Element, document: nodes.document, noqa: bool,
+        self,
+        node: nodes.Element,
+        patch: nodes.Element,
+        document: nodes.document,
+        noqa: bool,
     ) -> None:
         self.node: nodes.Element = node
         self.patch: nodes.Element = patch
         self.document: nodes.document = document
         self.noqa: bool = noqa
 
-    def compare_references(self, old_refs: Sequence[nodes.Element],
-                           new_refs: Sequence[nodes.Element],
-                           warning_msg: str) -> None:
+    def compare_references(
+        self,
+        old_refs: Sequence[nodes.Element],
+        new_refs: Sequence[nodes.Element],
+        warning_msg: str,
+    ) -> None:
         """Warn about mismatches between references in original and translated content."""
         # FIXME: could use a smarter strategy than len(old_refs) == len(new_refs)
         if not self.noqa and len(old_refs) != len(new_refs):
             old_ref_rawsources = [ref.rawsource for ref in old_refs]
             new_ref_rawsources = [ref.rawsource for ref in new_refs]
-            logger.warning(warning_msg.format(old_ref_rawsources, new_ref_rawsources),
-                           location=self.node, type='i18n', subtype='inconsistent_references')
+            logger.warning(
+                warning_msg.format(old_ref_rawsources, new_ref_rawsources),
+                location=self.node,
+                type='i18n',
+                subtype='inconsistent_references',
+            )
 
     def update_title_mapping(self) -> bool:
         processed = False  # skip flag
 
         # update title(section) target name-id mapping
-        if isinstance(self.node, nodes.title) and isinstance(self.node.parent, nodes.section):
+        if (
+            isinstance(self.node, nodes.title)
+            and isinstance(self.node.parent, nodes.section)
+        ):  # fmt: skip
             section_node = self.node.parent
             new_name = nodes.fully_normalize_name(self.patch.astext())
             old_name = nodes.fully_normalize_name(self.node.astext())
@@ -201,9 +223,14 @@ class _NodeUpdater:
         is_autofootnote_ref = NodeMatcher(nodes.footnote_reference, auto=Any)
         old_foot_refs = list(is_autofootnote_ref.findall(self.node))
         new_foot_refs = list(is_autofootnote_ref.findall(self.patch))
-        self.compare_references(old_foot_refs, new_foot_refs,
-                                __('inconsistent footnote references in translated message.' +
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_foot_refs,
+            new_foot_refs,
+            __(
+                'inconsistent footnote references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         old_foot_namerefs: dict[str, list[nodes.footnote_reference]] = {}
         for r in old_foot_refs:
             old_foot_namerefs.setdefault(r.get('refname'), []).append(r)
@@ -241,9 +268,14 @@ class _NodeUpdater:
         is_refnamed_ref = NodeMatcher(nodes.reference, refname=Any)
         old_refs = list(is_refnamed_ref.findall(self.node))
         new_refs = list(is_refnamed_ref.findall(self.patch))
-        self.compare_references(old_refs, new_refs,
-                                __('inconsistent references in translated message.' +
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_refs,
+            new_refs,
+            __(
+                'inconsistent references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         old_ref_names = [r['refname'] for r in old_refs]
         new_ref_names = [r['refname'] for r in new_refs]
         orphans = [*({*old_ref_names} - {*new_ref_names})]
@@ -266,31 +298,41 @@ class _NodeUpdater:
         old_foot_refs = list(is_refnamed_footnote_ref.findall(self.node))
         new_foot_refs = list(is_refnamed_footnote_ref.findall(self.patch))
         refname_ids_map: dict[str, list[str]] = {}
-        self.compare_references(old_foot_refs, new_foot_refs,
-                                __('inconsistent footnote references in translated message.' +
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_foot_refs,
+            new_foot_refs,
+            __(
+                'inconsistent footnote references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         for oldf in old_foot_refs:
-            refname_ids_map.setdefault(oldf["refname"], []).append(oldf["ids"])
+            refname_ids_map.setdefault(oldf['refname'], []).append(oldf['ids'])
         for newf in new_foot_refs:
-            refname = newf["refname"]
+            refname = newf['refname']
             if refname_ids_map.get(refname):
-                newf["ids"] = refname_ids_map[refname].pop(0)
+                newf['ids'] = refname_ids_map[refname].pop(0)
 
     def update_citation_references(self) -> None:
         # citation should use original 'ids'.
         is_citation_ref = NodeMatcher(nodes.citation_reference, refname=Any)
         old_cite_refs = list(is_citation_ref.findall(self.node))
         new_cite_refs = list(is_citation_ref.findall(self.patch))
-        self.compare_references(old_cite_refs, new_cite_refs,
-                                __('inconsistent citation references in translated message.' +
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_cite_refs,
+            new_cite_refs,
+            __(
+                'inconsistent citation references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         refname_ids_map: dict[str, list[str]] = {}
         for oldc in old_cite_refs:
-            refname_ids_map.setdefault(oldc["refname"], []).append(oldc["ids"])
+            refname_ids_map.setdefault(oldc['refname'], []).append(oldc['ids'])
         for newc in new_cite_refs:
-            refname = newc["refname"]
+            refname = newc['refname']
             if refname_ids_map.get(refname):
-                newc["ids"] = refname_ids_map[refname].pop()
+                newc['ids'] = refname_ids_map[refname].pop()
 
     def update_pending_xrefs(self) -> None:
         # Original pending_xref['reftarget'] contain not-translated
@@ -298,20 +340,25 @@ class _NodeUpdater:
         # This code restricts to change ref-targets in the translation.
         old_xrefs = [*self.node.findall(addnodes.pending_xref)]
         new_xrefs = [*self.patch.findall(addnodes.pending_xref)]
-        self.compare_references(old_xrefs, new_xrefs,
-                                __('inconsistent term references in translated message.' +
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_xrefs,
+            new_xrefs,
+            __(
+                'inconsistent term references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
 
         xref_reftarget_map: dict[tuple[str, str, str] | None, dict[str, Any]] = {}
 
         def get_ref_key(node: addnodes.pending_xref) -> tuple[str, str, str] | None:
-            case = node["refdomain"], node["reftype"]
+            case = node['refdomain'], node['reftype']
             if case == ('std', 'term'):
                 return None
             else:
                 return (
-                    node["refdomain"],
-                    node["reftype"],
+                    node['refdomain'],
+                    node['reftype'],
                     node['reftarget'],
                 )
 
@@ -347,8 +394,10 @@ class Locale(SphinxTransform):
         textdomain = docname_to_domain(self.env.docname, self.config.gettext_compact)
 
         # fetch translations
-        dirs = [path.join(self.env.srcdir, directory)
-                for directory in self.config.locale_dirs]
+        dirs = [
+            path.join(self.env.srcdir, directory)
+            for directory in self.config.locale_dirs
+        ]
         catalog, has_catalog = init_locale(dirs, self.config.language, textdomain)
         if not has_catalog:
             return
@@ -393,8 +442,14 @@ class Locale(SphinxTransform):
             if isinstance(node, LITERAL_TYPE_NODES):
                 msgstr = '::\n\n' + indent(msgstr, ' ' * 3)
 
-            patch = publish_msgstr(self.app, msgstr, source,
-                                   node.line, self.config, settings)  # type: ignore[arg-type]
+            patch = publish_msgstr(
+                self.app,
+                msgstr,
+                source,
+                node.line,  # type: ignore[arg-type]
+                self.config,
+                settings,
+            )
             # FIXME: no warnings about inconsistent references in this part
             # XXX doctest and other block markup
             if not isinstance(patch, nodes.paragraph):
@@ -408,11 +463,21 @@ class Locale(SphinxTransform):
                 for _id in node['ids']:
                     term, first_classifier = split_term_classifiers(msgstr)
                     patch = publish_msgstr(
-                        self.app, term or '', source, node.line, self.config, settings,  # type: ignore[arg-type]
+                        self.app,
+                        term or '',
+                        source,
+                        node.line,  # type: ignore[arg-type]
+                        self.config,
+                        settings,
                     )
                     updater.patch = make_glossary_term(
-                        self.env, patch, first_classifier,
-                        source, node.line, _id, self.document,  # type: ignore[arg-type]
+                        self.env,
+                        patch,
+                        first_classifier,
+                        source,
+                        node.line,  # type: ignore[arg-type]
+                        _id,
+                        self.document,
                     )
                     processed = True
 
@@ -474,8 +539,14 @@ class Locale(SphinxTransform):
                 # This generates: <section ...><title>msgstr</title></section>
                 msgstr = msgstr + '\n' + '=' * len(msgstr) * 2
 
-            patch = publish_msgstr(self.app, msgstr, source,
-                                   node.line, self.config, settings)  # type: ignore[arg-type]
+            patch = publish_msgstr(
+                self.app,
+                msgstr,
+                source,
+                node.line,  # type: ignore[arg-type]
+                self.config,
+                settings,
+            )
             # Structural Subelements phase2
             if isinstance(node, nodes.title):
                 # get <title> node that placed as a first child
@@ -483,8 +554,8 @@ class Locale(SphinxTransform):
 
             # ignore unexpected markups in translation message
             unexpected: tuple[type[nodes.Element], ...] = (
-                nodes.paragraph,    # expected form of translation
-                nodes.title,        # generated by above "Subelements phase2"
+                nodes.paragraph,  # expected form of translation
+                nodes.title,  # generated by above "Subelements phase2"
             )
 
             # following types are expected if
@@ -527,7 +598,13 @@ class Locale(SphinxTransform):
                             msgstr = part
                         msgstr_parts.append(msgstr)
 
-                    new_entry = entry_type, ';'.join(msgstr_parts), target_id, main, None
+                    new_entry = (
+                        entry_type,
+                        ';'.join(msgstr_parts),
+                        target_id,
+                        main,
+                        None,
+                    )
                     new_entries.append(new_entry)
 
                 node['raw_entries'] = entries
@@ -543,6 +620,7 @@ class TranslationProgressTotaliser(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         from sphinx.builders.gettext import MessageCatalogBuilder
+
         if isinstance(self.app.builder, MessageCatalogBuilder):
             return
 
@@ -567,6 +645,7 @@ class AddTranslationClasses(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         from sphinx.builders.gettext import MessageCatalogBuilder
+
         if isinstance(self.app.builder, MessageCatalogBuilder):
             return
 
@@ -582,8 +661,10 @@ class AddTranslationClasses(SphinxTransform):
             add_translated = False
             add_untranslated = True
         else:
-            msg = ('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 NodeMatcher(nodes.Element, translated=Any).findall(self.document):
@@ -604,6 +685,7 @@ class RemoveTranslatableInline(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         from sphinx.builders.gettext import MessageCatalogBuilder
+
         if isinstance(self.app.builder, MessageCatalogBuilder):
             return