Sphinx 8.1.2__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/registry.py

@@ -6,9 +6,9 @@ import traceback
 from importlib import import_module
 from importlib.metadata import entry_points
 from types import MethodType
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
-from sphinx.domains import Domain, Index, ObjType
+from sphinx.domains import ObjType
 from sphinx.domains.std import GenericObject, Target
 from sphinx.errors import ExtensionError, SphinxError, VersionRequirementError
 from sphinx.extension import Extension
@@ -17,10 +17,13 @@ from sphinx.locale import __
 from sphinx.parsers import Parser as SphinxParser
 from sphinx.roles import XRefRole
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.logging import prefixed_warnings
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Sequence
+    import os
+    from collections.abc import Callable, Iterator, Mapping, Sequence
+    from typing import Any, TypeAlias
 
     from docutils import nodes
     from docutils.core import Publisher
@@ -29,26 +32,43 @@ if TYPE_CHECKING:
     from docutils.parsers.rst import Directive
     from docutils.transforms import Transform
 
+    from sphinx import addnodes
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
     from sphinx.config import Config
+    from sphinx.domains import Domain, Index
     from sphinx.environment import BuildEnvironment
     from sphinx.ext.autodoc import Documenter
+    from sphinx.util.docfields import Field
     from sphinx.util.typing import (
         ExtensionMetadata,
         RoleFunction,
         TitleGetter,
         _ExtensionSetupFunc,
     )
+    from sphinx.writers.html5 import HTML5Translator
+
+    # visit/depart function
+    # the parameters should be (SphinxTranslator, Element)
+    # or any subtype of either, but mypy rejects this.
+    _NodeHandler: TypeAlias = Callable[[Any, Any], None]
+    _NodeHandlerPair: TypeAlias = tuple[_NodeHandler, _NodeHandler | None]
+
+    _MathsRenderer: TypeAlias = Callable[[HTML5Translator, nodes.math], None]
+    _MathsBlockRenderer: TypeAlias = Callable[[HTML5Translator, nodes.math_block], None]
+    _MathsInlineRenderers: TypeAlias = tuple[_MathsRenderer, _MathsRenderer | None]
+    _MathsBlockRenderers: TypeAlias = tuple[
+        _MathsBlockRenderer, _MathsBlockRenderer | None
+    ]
 
 logger = logging.getLogger(__name__)
 
 # list of deprecated extensions. Keys are extension name.
 # Values are Sphinx version that merge the extension.
 EXTENSION_BLACKLIST = {
-    "sphinxjp.themecore": "1.2",
+    'sphinxjp.themecore': '1.2',
     'sphinxcontrib-napoleon': '1.3',
-    "sphinxprettysearchresults": "2.0.0",
+    'sphinxprettysearchresults': '2.0.0',
 }
 
 
@@ -91,16 +111,20 @@ class SphinxComponentRegistry:
 
         #: HTML inline and block math renderers
         #: a dict of name -> tuple of visit function and depart function
-        self.html_inline_math_renderers: dict[str,
-                                              tuple[Callable, Callable | None]] = {}
-        self.html_block_math_renderers: dict[str,
-                                             tuple[Callable, Callable | None]] = {}
+        self.html_inline_math_renderers: dict[
+            str,
+            _MathsInlineRenderers,
+        ] = {}
+        self.html_block_math_renderers: dict[
+            str,
+            _MathsBlockRenderers,
+        ] = {}
 
         #: HTML assets
         self.html_assets_policy: str = 'per_page'
 
         #: HTML themes
-        self.html_themes: dict[str, str] = {}
+        self.html_themes: dict[str, _StrPath] = {}
 
         #: js_files; list of JS paths or URLs
         self.js_files: list[tuple[str | None, dict[str, Any]]] = []
@@ -124,7 +148,7 @@ class SphinxComponentRegistry:
 
         #: custom handlers for translators
         #: a dict of builder name -> dict of node name -> visitor and departure functions
-        self.translation_handlers: dict[str, dict[str, tuple[Callable, Callable | None]]] = {}
+        self.translation_handlers: dict[str, dict[str, _NodeHandlerPair]] = {}
 
         #: additional transforms; list of transforms
         self.transforms: list[type[Transform]] = []
@@ -139,10 +163,14 @@ class SphinxComponentRegistry:
     def add_builder(self, builder: type[Builder], override: bool = False) -> None:
         logger.debug('[app] adding builder: %r', builder)
         if not hasattr(builder, 'name'):
-            raise ExtensionError(__('Builder class %s has no "name" attribute') % builder)
+            raise ExtensionError(
+                __('Builder class %s has no "name" attribute') % builder
+            )
         if builder.name in self.builders and not override:
-            raise ExtensionError(__('Builder %r already exists (in module %s)') %
-                                 (builder.name, self.builders[builder.name].__module__))
+            raise ExtensionError(
+                __('Builder %r already exists (in module %s)')
+                % (builder.name, self.builders[builder.name].__module__)
+            )
         self.builders[builder.name] = builder
 
     def preload_builder(self, app: Sphinx, name: str) -> None:
@@ -154,8 +182,13 @@ class SphinxComponentRegistry:
             try:
                 entry_point = builder_entry_points[name]
             except KeyError as exc:
-                raise SphinxError(__('Builder name %s not registered or available'
-                                     ' through entry point') % name) from exc
+                raise SphinxError(
+                    __(
+                        'Builder name %s not registered or available'
+                        ' through entry point'
+                    )
+                    % name
+                ) from exc
 
             self.load_extension(app, entry_point.module)
 
@@ -187,39 +220,52 @@ class SphinxComponentRegistry:
 
             yield domain
 
-    def add_directive_to_domain(self, domain: str, name: str,
-                                cls: type[Directive], override: bool = False) -> None:
+    def add_directive_to_domain(
+        self, domain: str, name: str, cls: type[Directive], override: bool = False
+    ) -> None:
         logger.debug('[app] adding directive to domain: %r', (domain, name, cls))
         if domain not in self.domains:
             raise ExtensionError(__('domain %s not yet registered') % domain)
 
-        directives: dict[str, type[Directive]] = self.domain_directives.setdefault(domain, {})
+        directives: dict[str, type[Directive]] = self.domain_directives.setdefault(
+            domain, {}
+        )
         if name in directives and not override:
-            raise ExtensionError(__('The %r directive is already registered to domain %s') %
-                                 (name, domain))
+            raise ExtensionError(
+                __('The %r directive is already registered to domain %s')
+                % (name, domain)
+            )
         directives[name] = cls
 
-    def add_role_to_domain(self, domain: str, name: str,
-                           role: RoleFunction | XRefRole, override: bool = False,
-                           ) -> None:
+    def add_role_to_domain(
+        self,
+        domain: str,
+        name: str,
+        role: RoleFunction | XRefRole,
+        override: bool = False,
+    ) -> None:
         logger.debug('[app] adding role to domain: %r', (domain, name, role))
         if domain not in self.domains:
             raise ExtensionError(__('domain %s not yet registered') % domain)
         roles = self.domain_roles.setdefault(domain, {})
         if name in roles and not override:
-            raise ExtensionError(__('The %r role is already registered to domain %s') %
-                                 (name, domain))
+            raise ExtensionError(
+                __('The %r role is already registered to domain %s') % (name, domain)
+            )
         roles[name] = role
 
-    def add_index_to_domain(self, domain: str, index: type[Index],
-                            override: bool = False) -> None:
+    def add_index_to_domain(
+        self, domain: str, index: type[Index], override: bool = False
+    ) -> None:
         logger.debug('[app] adding index to domain: %r', (domain, index))
         if domain not in self.domains:
             raise ExtensionError(__('domain %s not yet registered') % domain)
         indices = self.domain_indices.setdefault(domain, [])
         if index in indices and not override:
-            raise ExtensionError(__('The %r index is already registered to domain %s') %
-                                 (index.name, domain))
+            raise ExtensionError(
+                __('The %r index is already registered to domain %s')
+                % (index.name, domain)
+            )
         indices.append(index)
 
     def add_object_type(
@@ -227,30 +273,45 @@ class SphinxComponentRegistry:
         directivename: str,
         rolename: str,
         indextemplate: str = '',
-        parse_node: Callable | None = None,
+        parse_node: Callable[[BuildEnvironment, str, addnodes.desc_signature], str]
+        | None = None,
         ref_nodeclass: type[TextElement] | None = None,
         objname: str = '',
-        doc_field_types: Sequence = (),
+        doc_field_types: Sequence[Field] = (),
         override: bool = False,
     ) -> None:
-        logger.debug('[app] adding object type: %r',
-                     (directivename, rolename, indextemplate, parse_node,
-                      ref_nodeclass, objname, doc_field_types))
+        logger.debug(
+            '[app] adding object type: %r',
+            (
+                directivename,
+                rolename,
+                indextemplate,
+                parse_node,
+                ref_nodeclass,
+                objname,
+                doc_field_types,
+            ),
+        )
 
         # create a subclass of GenericObject as the new directive
-        directive = type(directivename,
-                         (GenericObject, object),
-                         {'indextemplate': indextemplate,
-                          'parse_node': parse_node and staticmethod(parse_node),
-                          'doc_field_types': doc_field_types})
+        directive = type(
+            directivename,
+            (GenericObject, object),
+            {
+                'indextemplate': indextemplate,
+                'parse_node': parse_node and staticmethod(parse_node),
+                'doc_field_types': doc_field_types,
+            },
+        )
 
         self.add_directive_to_domain('std', directivename, directive)
         self.add_role_to_domain('std', rolename, XRefRole(innernodeclass=ref_nodeclass))
 
         object_types = self.domain_object_types.setdefault('std', {})
         if directivename in object_types and not override:
-            raise ExtensionError(__('The %r object_type is already registered') %
-                                 directivename)
+            raise ExtensionError(
+                __('The %r object_type is already registered') % directivename
+            )
         object_types[directivename] = ObjType(objname or directivename, rolename)
 
     def add_crossref_type(
@@ -262,24 +323,31 @@ class SphinxComponentRegistry:
         objname: str = '',
         override: bool = False,
     ) -> None:
-        logger.debug('[app] adding crossref type: %r',
-                     (directivename, rolename, indextemplate, ref_nodeclass, objname))
+        logger.debug(
+            '[app] adding crossref type: %r',
+            (directivename, rolename, indextemplate, ref_nodeclass, objname),
+        )
 
         # create a subclass of Target as the new directive
-        directive = type(directivename,
-                         (Target, object),
-                         {'indextemplate': indextemplate})
+        directive = type(
+            directivename,
+            (Target, object),
+            {'indextemplate': indextemplate},
+        )
 
         self.add_directive_to_domain('std', directivename, directive)
         self.add_role_to_domain('std', rolename, XRefRole(innernodeclass=ref_nodeclass))
 
         object_types = self.domain_object_types.setdefault('std', {})
         if directivename in object_types and not override:
-            raise ExtensionError(__('The %r crossref_type is already registered') %
-                                 directivename)
+            raise ExtensionError(
+                __('The %r crossref_type is already registered') % directivename
+            )
         object_types[directivename] = ObjType(objname or directivename, rolename)
 
-    def add_source_suffix(self, suffix: str, filetype: str, override: bool = False) -> None:
+    def add_source_suffix(
+        self, suffix: str, filetype: str, override: bool = False
+    ) -> None:
         logger.debug('[app] adding source_suffix: %r, %r', suffix, filetype)
         if suffix in self.source_suffix and not override:
             raise ExtensionError(__('source_suffix %r is already registered') % suffix)
@@ -291,15 +359,18 @@ class SphinxComponentRegistry:
         # create a map from filetype to parser
         for filetype in parser.supported:
             if filetype in self.source_parsers and not override:
-                raise ExtensionError(__('source_parser for %r is already registered') %
-                                     filetype)
+                raise ExtensionError(
+                    __('source_parser for %r is already registered') % filetype
+                )
             self.source_parsers[filetype] = parser
 
     def get_source_parser(self, filetype: str) -> type[Parser]:
         try:
             return self.source_parsers[filetype]
         except KeyError as exc:
-            raise SphinxError(__('Source parser for %s not registered') % filetype) from exc
+            raise SphinxError(
+                __('Source parser for %s not registered') % filetype
+            ) from exc
 
     def get_source_parsers(self) -> dict[str, type[Parser]]:
         return self.source_parsers
@@ -311,28 +382,32 @@ class SphinxComponentRegistry:
             parser.set_application(app)
         return parser
 
-    def add_translator(self, name: str, translator: type[nodes.NodeVisitor],
-                       override: bool = False) -> None:
+    def add_translator(
+        self, name: str, translator: type[nodes.NodeVisitor], override: bool = False
+    ) -> None:
         logger.debug('[app] Change of translator for the %s builder.', name)
         if name in self.translators and not override:
             raise ExtensionError(__('Translator for %r already exists') % name)
         self.translators[name] = translator
 
     def add_translation_handlers(
-        self,
-        node: type[Element],
-        **kwargs: tuple[Callable, Callable | None],
+        self, node: type[Element], **kwargs: _NodeHandlerPair
     ) -> None:
         logger.debug('[app] adding translation_handlers: %r, %r', node, kwargs)
         for builder_name, handlers in kwargs.items():
-            translation_handlers = self.translation_handlers.setdefault(builder_name, {})
+            translation_handlers = self.translation_handlers.setdefault(
+                builder_name, {}
+            )
             try:
                 visit, depart = handlers  # unpack once for assertion
                 translation_handlers[node.__name__] = (visit, depart)
             except ValueError as exc:
                 raise ExtensionError(
-                    __('kwargs for add_node() must be a (visit, depart) '
-                       'function tuple: %r=%r') % (builder_name, handlers),
+                    __(
+                        'kwargs for add_node() must be a (visit, depart) '
+                        'function tuple: %r=%r'
+                    )
+                    % (builder_name, handlers),
                 ) from exc
 
     def get_translator_class(self, builder: Builder) -> type[nodes.NodeVisitor]:
@@ -379,8 +454,9 @@ class SphinxComponentRegistry:
     def add_documenter(self, objtype: str, documenter: type[Documenter]) -> None:
         self.documenters[objtype] = documenter
 
-    def add_autodoc_attrgetter(self, typ: type,
-                               attrgetter: Callable[[Any, str, Any], Any]) -> None:
+    def add_autodoc_attrgetter(
+        self, typ: type, attrgetter: Callable[[Any, str, Any], Any]
+    ) -> None:
         self.autodoc_attrgetters[typ] = attrgetter
 
     def add_css_files(self, filename: str, **attributes: Any) -> None:
@@ -395,7 +471,7 @@ class SphinxComponentRegistry:
         return bool([x for x in packages if x[0] == name])
 
     def add_latex_package(
-        self, name: str, options: str | None, after_hyperref: bool = False,
+        self, name: str, options: str | None, after_hyperref: bool = False
     ) -> None:
         if self.has_latex_package(name):
             logger.warning("latex package '%s' already included", name)
@@ -410,9 +486,12 @@ class SphinxComponentRegistry:
         self,
         node: type[Node],
         figtype: str,
-        title_getter: TitleGetter | None = None, override: bool = False,
+        title_getter: TitleGetter | None = None,
+        override: bool = False,
     ) -> None:
-        logger.debug('[app] adding enumerable node: (%r, %r, %r)', node, figtype, title_getter)
+        logger.debug(
+            '[app] adding enumerable node: (%r, %r, %r)', node, figtype, title_getter
+        )
         if node in self.enumerable_nodes and not override:
             raise ExtensionError(__('enumerable_node %r already registered') % node)
         self.enumerable_nodes[node] = (figtype, title_getter)
@@ -420,11 +499,15 @@ class SphinxComponentRegistry:
     def add_html_math_renderer(
         self,
         name: str,
-        inline_renderers: tuple[Callable, Callable | None] | None,
-        block_renderers: tuple[Callable, Callable | None] | None,
+        inline_renderers: _MathsInlineRenderers | None,
+        block_renderers: _MathsBlockRenderers | None,
     ) -> None:
-        logger.debug('[app] adding html_math_renderer: %s, %r, %r',
-                     name, inline_renderers, block_renderers)
+        logger.debug(
+            '[app] adding html_math_renderer: %s, %r, %r',
+            name,
+            inline_renderers,
+            block_renderers,
+        )
         if name in self.html_inline_math_renderers:
             raise ExtensionError(__('math renderer %s is already registered') % name)
 
@@ -433,17 +516,22 @@ class SphinxComponentRegistry:
         if block_renderers is not None:
             self.html_block_math_renderers[name] = block_renderers
 
-    def add_html_theme(self, name: str, theme_path: str) -> None:
-        self.html_themes[name] = theme_path
+    def add_html_theme(self, name: str, theme_path: str | os.PathLike[str]) -> None:
+        self.html_themes[name] = _StrPath(theme_path)
 
     def load_extension(self, app: Sphinx, extname: str) -> None:
         """Load a Sphinx extension."""
         if extname in app.extensions:  # already loaded
             return
         if extname in EXTENSION_BLACKLIST:
-            logger.warning(__('the extension %r was already merged with Sphinx since '
-                              'version %s; this extension is ignored.'),
-                           extname, EXTENSION_BLACKLIST[extname])
+            logger.warning(
+                __(
+                    'the extension %r was already merged with Sphinx since '
+                    'version %s; this extension is ignored.'
+                ),
+                extname,
+                EXTENSION_BLACKLIST[extname],
+            )
             return
 
         # update loading context
@@ -453,13 +541,19 @@ class SphinxComponentRegistry:
                 mod = import_module(extname)
             except ImportError as err:
                 logger.verbose(__('Original exception:\n') + traceback.format_exc())
-                raise ExtensionError(__('Could not import extension %s') % extname,
-                                     err) from err
+                raise ExtensionError(
+                    __('Could not import extension %s') % extname, err
+                ) from err
 
             setup: _ExtensionSetupFunc | None = getattr(mod, 'setup', None)
             if setup is None:
-                logger.warning(__('extension %r has no setup() function; is it really '
-                                  'a Sphinx extension module?'), extname)
+                logger.warning(
+                    __(
+                        'extension %r has no setup() function; is it really '
+                        'a Sphinx extension module?'
+                    ),
+                    extname,
+                )
                 metadata: ExtensionMetadata = {}
             else:
                 try:
@@ -467,27 +561,33 @@ class SphinxComponentRegistry:
                 except VersionRequirementError as err:
                     # add the extension name to the version required
                     raise VersionRequirementError(
-                        __('The %s extension used by this project needs at least '
-                           'Sphinx v%s; it therefore cannot be built with this '
-                           'version.') % (extname, err),
+                        __(
+                            'The %s extension used by this project needs at least '
+                            'Sphinx v%s; it therefore cannot be built with this '
+                            'version.'
+                        )
+                        % (extname, err),
                     ) from err
 
             if metadata is None:
                 metadata = {}
             elif not isinstance(metadata, dict):
-                logger.warning(__('extension %r returned an unsupported object from '
-                                  'its setup() function; it should return None or a '
-                                  'metadata dictionary'), extname)
+                logger.warning(
+                    __(
+                        'extension %r returned an unsupported object from '
+                        'its setup() function; it should return None or a '
+                        'metadata dictionary'
+                    ),
+                    extname,
+                )
                 metadata = {}
 
             app.extensions[extname] = Extension(extname, mod, **metadata)
 
-    def get_envversion(self, app: Sphinx) -> dict[str, int]:
-        from sphinx.environment import ENV_VERSION
-        envversion = {ext.name: ext.metadata['env_version'] for ext in app.extensions.values()
-                      if ext.metadata.get('env_version')}
-        envversion['sphinx'] = ENV_VERSION
-        return envversion
+    def get_envversion(self, app: Sphinx) -> Mapping[str, int]:
+        from sphinx.environment import _get_env_version
+
+        return _get_env_version(app.extensions)
 
     def get_publisher(self, app: Sphinx, filetype: str) -> Publisher:
         try:
@@ -502,7 +602,7 @@ class SphinxComponentRegistry:
 def merge_source_suffix(app: Sphinx, config: Config) -> None:
     """Merge any user-specified source_suffix with any added by extensions."""
     for suffix, filetype in app.registry.source_suffix.items():
-        if suffix not in app.config.source_suffix:  # NoQA: SIM114
+        if suffix not in app.config.source_suffix:
             app.config.source_suffix[suffix] = filetype
         elif app.config.source_suffix[suffix] == 'restructuredtext':
             # The filetype is not specified (default filetype).

sphinx/roles.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 import docutils.parsers.rst.directives
 import docutils.parsers.rst.roles
@@ -17,7 +17,7 @@ from sphinx.util.docutils import ReferenceRole, SphinxRole
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from typing import Final
+    from typing import Any, Final
 
     from docutils.nodes import Element, Node, TextElement, system_message
 
@@ -29,7 +29,6 @@ if TYPE_CHECKING:
 generic_docroles = {
     'command': addnodes.literal_strong,
     'dfn': nodes.emphasis,
-    'kbd': nodes.literal,
     'mailheader': addnodes.literal_emphasis,
     'makevar': addnodes.literal_strong,
     'mimetype': addnodes.literal_emphasis,
@@ -43,8 +42,7 @@ generic_docroles = {
 
 
 class XRefRole(ReferenceRole):
-    """
-    A generic cross-referencing role.  To create a callable that can be used as
+    """A generic cross-referencing role.  To create a callable that can be used as
     a role function, create an instance of this class.
 
     The general features of this role are:
@@ -371,8 +369,7 @@ class RFC(ReferenceRole):
 
 
 def _format_rfc_target(target: str, /) -> str:
-    """
-    Takes an RFC number with an optional anchor (like ``123#section-2.5.3``)
+    """Takes an RFC number with an optional anchor (like ``123#section-2.5.3``)
     and attempts to produce a human-friendly title for it.
 
     We have a set of known anchors that we format nicely,
@@ -479,6 +476,59 @@ class Abbreviation(SphinxRole):
         return [nodes.abbreviation(self.rawtext, text, **options)], []
 
 
+class Keyboard(SphinxRole):
+    """Implement the :kbd: role.
+
+    Split words in the text by separator or whitespace,
+    but keep multi-word keys together.
+    """
+
+    # capture ('-', '+', '^', or whitespace) in between any two characters
+    _pattern: Final = re.compile(r'(?<=.)([\-+^]| +)(?=.)')
+
+    def run(self) -> tuple[list[Node], list[system_message]]:
+        classes = ['kbd']
+        if 'classes' in self.options:
+            classes.extend(self.options['classes'])
+
+        parts = self._pattern.split(self.text)
+        if len(parts) == 1 or self._is_multi_word_key(parts):
+            return [nodes.literal(self.rawtext, self.text, classes=classes)], []
+
+        compound: list[Node] = []
+        while parts:
+            if self._is_multi_word_key(parts):
+                key = ''.join(parts[:3])
+                parts[:3] = []
+            else:
+                key = parts.pop(0)
+            compound.append(nodes.literal(key, key, classes=classes))
+
+            try:
+                sep = parts.pop(0)  # key separator ('-', '+', '^', etc)
+            except IndexError:
+                break
+            else:
+                compound.append(nodes.Text(sep))
+
+        return compound, []
+
+    @staticmethod
+    def _is_multi_word_key(parts: list[str]) -> bool:
+        if len(parts) <= 2 or not parts[1].isspace():
+            return False
+        name = parts[0].lower(), parts[2].lower()
+        return name in frozenset({
+            ('back', 'space'),
+            ('caps', 'lock'),
+            ('num', 'lock'),
+            ('page', 'down'),
+            ('page', 'up'),
+            ('scroll', 'lock'),
+            ('sys', 'rq'),
+        })
+
+
 class Manpage(ReferenceRole):
     _manpage_re = re.compile(r'^(?P<path>(?P<page>.+)[(.](?P<section>[1-9]\w*)?\)?)$')
 
@@ -576,6 +626,7 @@ specific_docroles: dict[str, RoleFunction] = {
     'samp': EmphasizedLiteral(),
     # other
     'abbr': Abbreviation(),
+    'kbd': Keyboard(),
     'manpage': Manpage(),
 }