Sphinx 7.3.7__py3-none-any.whl → 7.4.0__py3-none-any.whl

sphinx/ext/coverage.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import glob
 import inspect
 import pickle
+import pkgutil
 import re
 import sys
 from importlib import import_module
@@ -23,7 +24,7 @@ from sphinx.util.console import red
 from sphinx.util.inspect import safe_getattr
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterable, Iterator, Sequence, Set
 
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
@@ -66,6 +67,93 @@ def _add_row(col_widths: list[int], columns: list[str], separator: str) -> Itera
     yield _add_line(col_widths, separator)
 
 
+def _load_modules(mod_name: str, ignored_module_exps: Iterable[re.Pattern[str]]) -> Set[str]:
+    """Recursively load all submodules.
+
+    :param mod_name: The name of a module to load submodules for.
+    :param ignored_module_exps: A list of regexes for modules to ignore.
+    :returns: A set of modules names including the provided module name,
+        ``mod_name``
+    :raises ImportError: If the module indicated by ``mod_name`` could not be
+        loaded.
+    """
+    if any(exp.match(mod_name) for exp in ignored_module_exps):
+        return set()
+
+    # This can raise an exception, which must be handled by the caller.
+    mod = import_module(mod_name)
+    modules = {mod_name}
+    if mod.__spec__ is None:
+        return modules
+
+    search_locations = mod.__spec__.submodule_search_locations
+    for (_, sub_mod_name, sub_mod_ispkg) in pkgutil.iter_modules(search_locations):
+        if sub_mod_name == '__main__':
+            continue
+
+        if sub_mod_ispkg:
+            modules |= _load_modules(f'{mod_name}.{sub_mod_name}', ignored_module_exps)
+        else:
+            if any(exp.match(sub_mod_name) for exp in ignored_module_exps):
+                continue
+            modules.add(f'{mod_name}.{sub_mod_name}')
+
+    return modules
+
+
+def _determine_py_coverage_modules(
+    coverage_modules: Sequence[str],
+    seen_modules: Set[str],
+    ignored_module_exps: Iterable[re.Pattern[str]],
+    py_undoc: dict[str, dict[str, Any]],
+) -> list[str]:
+    """Return a sorted list of modules to check for coverage.
+
+    Figure out which of the two operating modes to use:
+
+    - If 'coverage_modules' is not specified, we check coverage for all modules
+      seen in the documentation tree. Any objects found in these modules that are
+      not documented will be noted. This will therefore only identify missing
+      objects, but it requires no additional configuration.
+
+    - If 'coverage_modules' is specified, we check coverage for all modules
+      specified in this configuration value. Any objects found in these modules
+      that are not documented will be noted. In addition, any objects from other
+      modules that are documented will be noted. This will therefore identify both
+      missing modules and missing objects, but it requires manual configuration.
+    """
+    if not coverage_modules:
+        return sorted(seen_modules)
+
+    modules: set[str] = set()
+    for mod_name in coverage_modules:
+        try:
+            modules |= _load_modules(mod_name, ignored_module_exps)
+        except ImportError as err:
+            # TODO(stephenfin): Define a subtype for all logs in this module
+            logger.warning(__('module %s could not be imported: %s'), mod_name, err)
+            py_undoc[mod_name] = {'error': err}
+            continue
+
+    # if there are additional modules then we warn but continue scanning
+    if additional_modules := seen_modules - modules:
+        logger.warning(
+            __('the following modules are documented but were not specified '
+               'in coverage_modules: %s'),
+            ', '.join(additional_modules),
+        )
+
+    # likewise, if there are missing modules we warn but continue scanning
+    if missing_modules := modules - seen_modules:
+        logger.warning(
+            __('the following modules are specified in coverage_modules '
+               'but were not documented'),
+            ', '.join(missing_modules),
+        )
+
+    return sorted(modules)
+
+
 class CoverageBuilder(Builder):
     """
     Evaluates coverage of code in the documentation.
@@ -106,12 +194,12 @@ class CoverageBuilder(Builder):
 
     def write(self, *ignored: Any) -> None:
         self.py_undoc: dict[str, dict[str, Any]] = {}
-        self.py_undocumented: dict[str, set[str]] = {}
-        self.py_documented: dict[str, set[str]] = {}
+        self.py_undocumented: dict[str, Set[str]] = {}
+        self.py_documented: dict[str, Set[str]] = {}
         self.build_py_coverage()
         self.write_py_coverage()
 
-        self.c_undoc: dict[str, set[tuple[str, str]]] = {}
+        self.c_undoc: dict[str, Set[tuple[str, str]]] = {}
         self.build_c_coverage()
         self.write_c_coverage()
 
@@ -169,11 +257,14 @@ class CoverageBuilder(Builder):
         )
 
     def build_py_coverage(self) -> None:
-        objects = self.env.domaindata['py']['objects']
-        modules = self.env.domaindata['py']['modules']
+        seen_objects = frozenset(self.env.domaindata['py']['objects'])
+        seen_modules = frozenset(self.env.domaindata['py']['modules'])
 
         skip_undoc = self.config.coverage_skip_undoc_in_source
 
+        modules = _determine_py_coverage_modules(
+            self.config.coverage_modules, seen_modules, self.mod_ignorexps, self.py_undoc,
+        )
         for mod_name in modules:
             ignore = False
             for exp in self.mod_ignorexps:
@@ -213,7 +304,7 @@ class CoverageBuilder(Builder):
                     continue
 
                 if inspect.isfunction(obj):
-                    if full_name not in objects:
+                    if full_name not in seen_objects:
                         for exp in self.fun_ignorexps:
                             if exp.match(name):
                                 break
@@ -229,7 +320,7 @@ class CoverageBuilder(Builder):
                         if exp.match(name):
                             break
                     else:
-                        if full_name not in objects:
+                        if full_name not in seen_objects:
                             if skip_undoc and not obj.__doc__:
                                 continue
                             # not documented at all
@@ -257,7 +348,7 @@ class CoverageBuilder(Builder):
                             full_attr_name = f'{full_name}.{attr_name}'
                             if self.ignore_pyobj(full_attr_name):
                                 continue
-                            if full_attr_name not in objects:
+                            if full_attr_name not in seen_objects:
                                 attrs.append(attr_name)
                                 undocumented_objects.add(full_attr_name)
                             else:
@@ -273,19 +364,17 @@ class CoverageBuilder(Builder):
 
     def _write_py_statistics(self, op: TextIO) -> None:
         """Outputs the table of ``op``."""
-        all_modules = set(self.py_documented.keys()).union(
-            set(self.py_undocumented.keys()))
-        all_objects: set[str] = set()
-        all_documented_objects: set[str] = set()
+        all_modules = frozenset(self.py_documented.keys() | self.py_undocumented.keys())
+        all_objects: Set[str] = set()
+        all_documented_objects: Set[str] = set()
         for module in all_modules:
-            all_module_objects = self.py_documented[module].union(self.py_undocumented[module])
-            all_objects = all_objects.union(all_module_objects)
-            all_documented_objects = all_documented_objects.union(self.py_documented[module])
+            all_objects |= self.py_documented[module] | self.py_undocumented[module]
+            all_documented_objects |= self.py_documented[module]
 
         # prepare tabular
         table = [['Module', 'Coverage', 'Undocumented']]
-        for module in all_modules:
-            module_objects = self.py_documented[module].union(self.py_undocumented[module])
+        for module in sorted(all_modules):
+            module_objects = self.py_documented[module] | self.py_undocumented[module]
             if len(module_objects):
                 value = 100.0 * len(self.py_documented[module]) / len(module_objects)
             else:
@@ -391,6 +480,7 @@ class CoverageBuilder(Builder):
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(CoverageBuilder)
+    app.add_config_value('coverage_modules', (), '', types={tuple, list})
     app.add_config_value('coverage_ignore_modules', [], '')
     app.add_config_value('coverage_ignore_functions', [], '')
     app.add_config_value('coverage_ignore_classes', [], '')

sphinx/ext/duration.py

@@ -13,10 +13,15 @@ from sphinx.locale import __
 from sphinx.util import logging
 
 if TYPE_CHECKING:
+    from typing import TypedDict
+
     from docutils import nodes
 
     from sphinx.application import Sphinx
 
+    class _DurationDomainData(TypedDict):
+        reading_durations: dict[str, float]
+
 logger = logging.getLogger(__name__)
 
 
@@ -38,9 +43,11 @@ class DurationDomain(Domain):
     def clear_doc(self, docname: str) -> None:
         self.reading_durations.pop(docname, None)
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, float]) -> None:
-        for docname, duration in otherdata.items():
-            if docname in docnames:
+    def merge_domaindata(self, docnames: list[str], otherdata: _DurationDomainData) -> None:  # type: ignore[override]
+        other_reading_durations = otherdata.get('reading_durations', {})
+        docnames_set = frozenset(docnames)
+        for docname, duration in other_reading_durations.items():
+            if docname in docnames_set:
                 self.reading_durations[docname] = duration
 
 

sphinx/ext/extlinks.py

@@ -91,9 +91,9 @@ class ExternalLinksChecker(SphinxPostTransform):
 
 def make_link_role(name: str, base_url: str, caption: str) -> RoleFunction:
     # Check whether we have base_url and caption strings have an '%s' for
-    # expansion.  If not, fall back the the old behaviour and use the string as
+    # expansion.  If not, fall back to the old behaviour and use the string as
     # a prefix.
-    # Remark: It is an implementation detail that we use Pythons %-formatting.
+    # Remark: It is an implementation detail that we use Python's %-formatting.
     # So far we only expose ``%s`` and require quoting of ``%`` using ``%%``.
     def role(typ: str, rawtext: str, text: str, lineno: int,
              inliner: Inliner, options: dict[str, Any] | None = None,
@@ -108,6 +108,7 @@ def make_link_role(name: str, base_url: str, caption: str) -> RoleFunction:
             else:
                 title = caption % part
         pnode = nodes.reference(title, title, internal=False, refuri=full_url)
+        pnode["classes"].append(f"extlink-{name}")
         return [pnode], []
     return role
 

sphinx/ext/graphviz.py

@@ -15,7 +15,7 @@ from typing import TYPE_CHECKING, Any, ClassVar
 from urllib.parse import urlsplit, urlunsplit
 
 from docutils import nodes
-from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst import directives
 
 import sphinx
 from sphinx.errors import SphinxError
@@ -91,12 +91,12 @@ class graphviz(nodes.General, nodes.Inline, nodes.Element):
     pass
 
 
-def figure_wrapper(directive: Directive, node: graphviz, caption: str) -> nodes.figure:
+def figure_wrapper(directive: SphinxDirective, node: graphviz, caption: str) -> nodes.figure:
     figure_node = nodes.figure('', node)
     if 'align' in node:
         figure_node['align'] = node.attributes.pop('align')
 
-    inodes, messages = directive.state.inline_text(caption, directive.lineno)
+    inodes, messages = directive.parse_inline(caption)
     caption_node = nodes.caption(caption, '', *inodes)
     caption_node.extend(messages)
     set_source_info(directive, caption_node)

sphinx/ext/ifconfig.py

@@ -22,7 +22,6 @@ from docutils import nodes
 
 import sphinx
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.nodes import nested_parse_with_titles
 
 if TYPE_CHECKING:
     from docutils.nodes import Node
@@ -48,7 +47,7 @@ class IfConfig(SphinxDirective):
         node.document = self.state.document
         self.set_source_info(node)
         node['expr'] = self.arguments[0]
-        nested_parse_with_titles(self.state, self.content, node, self.content_offset)
+        node += self.parse_content_to_nodes(allow_section_headings=True)
         return [node]
 
 

sphinx/ext/imgconverter.py

@@ -26,6 +26,7 @@ class ImagemagickConverter(ImageConverter):
         ('image/gif', 'image/png'),
         ('application/pdf', 'image/png'),
         ('application/illustrator', 'image/png'),
+        ('image/webp', 'image/png'),
     ]
 
     def is_available(self) -> bool:

sphinx/ext/imgmath.py

@@ -103,16 +103,17 @@ def generate_latex_macro(image_format: str,
     }
 
     if config.imgmath_use_preview:
-        template_name = 'preview.tex_t'
+        template_name = 'preview.tex'
     else:
-        template_name = 'template.tex_t'
+        template_name = 'template.tex'
 
     for template_dir in config.templates_path:
-        template = path.join(confdir, template_dir, template_name)
-        if path.exists(template):
-            return LaTeXRenderer().render(template, variables)
+        for template_suffix in ('.jinja', '_t'):
+            template = path.join(confdir, template_dir, template_name + template_suffix)
+            if path.exists(template):
+                return LaTeXRenderer().render(template, variables)
 
-    return LaTeXRenderer(templates_path).render(template_name, variables)
+    return LaTeXRenderer(templates_path).render(template_name + '.jinja', variables)
 
 
 def ensure_tempdir(builder: Builder) -> str:

sphinx/ext/inheritance_diagram.py

@@ -378,15 +378,15 @@ class InheritanceDiagram(SphinxDirective):
                 aliases=self.config.inheritance_alias,
                 top_classes=node['top-classes'])
         except InheritanceException as err:
-            return [node.document.reporter.warning(err, line=self.lineno)]  # type: ignore[union-attr]
+            return [node.document.reporter.warning(err, line=self.lineno)]
 
         # Create xref nodes for each target of the graph's image map and
         # add them to the doc tree so that Sphinx can resolve the
         # references to real URLs later.  These nodes will eventually be
         # removed from the doctree after we're done with them.
         for name in graph.get_all_class_names():
-            refnodes, x = class_role(  # type: ignore[call-arg,misc]
-                'class', ':class:`%s`' % name, name, 0, self.state)
+            refnodes, x = class_role(  # type: ignore[misc]
+                'class', ':class:`%s`' % name, name, 0, self.state.inliner)
             node.extend(refnodes)
         # Store the graph object so we can use it to generate the
         # dot file later

sphinx/ext/intersphinx/__init__.py

@@ -0,0 +1,81 @@
+"""Insert links to objects documented in remote Sphinx documentation.
+
+This works as follows:
+
+* Each Sphinx HTML build creates a file named "objects.inv" that contains a
+  mapping from object names to URIs relative to the HTML set's root.
+
+* Projects using the Intersphinx extension can specify links to such mapping
+  files in the `intersphinx_mapping` config value.  The mapping will then be
+  used to resolve otherwise missing references to objects into links to the
+  other documentation.
+
+* By default, the mapping file is assumed to be at the same location as the
+  rest of the documentation; however, the location of the mapping file can
+  also be specified individually, e.g. if the docs should be buildable
+  without Internet access.
+"""
+
+from __future__ import annotations
+
+__all__ = (
+    'InventoryAdapter',
+    'fetch_inventory',
+    'fetch_inventory_group',
+    'load_mappings',
+    'normalize_intersphinx_mapping',
+    'IntersphinxRoleResolver',
+    'inventory_exists',
+    'install_dispatcher',
+    'resolve_reference_in_inventory',
+    'resolve_reference_any_inventory',
+    'resolve_reference_detect_inventory',
+    'missing_reference',
+    'IntersphinxDispatcher',
+    'IntersphinxRole',
+    'inspect_main',
+)
+
+from typing import TYPE_CHECKING
+
+import sphinx
+from sphinx.ext.intersphinx._cli import inspect_main
+from sphinx.ext.intersphinx._load import (
+    fetch_inventory,
+    fetch_inventory_group,
+    load_mappings,
+    normalize_intersphinx_mapping,
+)
+from sphinx.ext.intersphinx._resolve import (
+    IntersphinxDispatcher,
+    IntersphinxRole,
+    IntersphinxRoleResolver,
+    install_dispatcher,
+    inventory_exists,
+    missing_reference,
+    resolve_reference_any_inventory,
+    resolve_reference_detect_inventory,
+    resolve_reference_in_inventory,
+)
+from sphinx.ext.intersphinx._shared import InventoryAdapter
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_config_value('intersphinx_mapping', {}, 'env')
+    app.add_config_value('intersphinx_cache_limit', 5, '')
+    app.add_config_value('intersphinx_timeout', None, '')
+    app.add_config_value('intersphinx_disabled_reftypes', ['std:doc'], 'env')
+    app.connect('config-inited', normalize_intersphinx_mapping, priority=800)
+    app.connect('builder-inited', load_mappings)
+    app.connect('source-read', install_dispatcher)
+    app.connect('missing-reference', missing_reference)
+    app.add_post_transform(IntersphinxRoleResolver)
+    return {
+        'version': sphinx.__display_version__,
+        'env_version': 1,
+        'parallel_read_safe': True,
+    }

sphinx/ext/intersphinx/__main__.py

@@ -0,0 +1,10 @@
+"""Command line interface for the intersphinx extension."""
+
+import logging as _logging
+import sys
+
+from sphinx.ext.intersphinx import inspect_main
+
+_logging.basicConfig()
+
+raise SystemExit(inspect_main(sys.argv[1:]))

sphinx/ext/intersphinx/_cli.py

@@ -0,0 +1,44 @@
+"""This module provides contains the code for intersphinx command-line utilities."""
+
+from __future__ import annotations
+
+import sys
+
+from sphinx.ext.intersphinx._load import fetch_inventory
+
+
+def inspect_main(argv: list[str], /) -> int:
+    """Debug functionality to print out an inventory"""
+    if len(argv) < 1:
+        print('Print out an inventory file.\n'
+              'Error: must specify local path or URL to an inventory file.',
+              file=sys.stderr)
+        return 1
+
+    class MockConfig:
+        intersphinx_timeout: int | None = None
+        tls_verify = False
+        tls_cacerts: str | dict[str, str] | None = None
+        user_agent: str = ''
+
+    class MockApp:
+        srcdir = ''
+        config = MockConfig()
+
+    try:
+        filename = argv[0]
+        inv_data = fetch_inventory(MockApp(), '', filename)  # type: ignore[arg-type]
+        for key in sorted(inv_data or {}):
+            print(key)
+            inv_entries = sorted(inv_data[key].items())
+            for entry, (_proj, _ver, url_path, display_name) in inv_entries:
+                display_name = display_name * (display_name != '-')
+                print(f'    {entry:<40} {display_name:<40}: {url_path}')
+    except ValueError as exc:
+        print(exc.args[0] % exc.args[1:], file=sys.stderr)
+        return 1
+    except Exception as exc:
+        print(f'Unknown error: {exc!r}', file=sys.stderr)
+        return 1
+    else:
+        return 0