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

sphinx/ext/intersphinx/_resolve.py

@@ -2,12 +2,11 @@
 
 from __future__ import annotations
 
-import posixpath
 import re
+from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
-from docutils.utils import relative_path
 
 from sphinx.addnodes import pending_xref
 from sphinx.deprecation import _deprecation_warning
@@ -16,9 +15,10 @@ from sphinx.ext.intersphinx._shared import LOGGER, InventoryAdapter
 from sphinx.locale import _, __
 from sphinx.transforms.post_transforms import ReferencesResolver
 from sphinx.util.docutils import CustomReSTDispatcher, SphinxRole
+from sphinx.util.osutil import _relative_path
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Iterable, Sequence, Set
     from types import ModuleType
     from typing import Any
 
@@ -27,31 +27,36 @@ if TYPE_CHECKING:
 
     from sphinx.application import Sphinx
     from sphinx.domains import Domain
+    from sphinx.domains._domains_container import _DomainsContainer
     from sphinx.environment import BuildEnvironment
     from sphinx.ext.intersphinx._shared import InventoryName
-    from sphinx.util.typing import Inventory, InventoryItem, RoleFunction
+    from sphinx.util.inventory import _InventoryItem
+    from sphinx.util.typing import Inventory, RoleFunction
 
 
 def _create_element_from_result(
-    domain: Domain,
+    domain_name: str,
     inv_name: InventoryName | None,
-    data: InventoryItem,
+    inv_item: _InventoryItem,
     node: pending_xref,
     contnode: TextElement,
 ) -> nodes.reference:
-    proj, version, uri, dispname = data
+    uri = inv_item.uri
     if '://' not in uri and node.get('refdoc'):
         # get correct path in case of subdirectories
-        uri = posixpath.join(relative_path(node['refdoc'], '.'), uri)
-    if version:
-        reftitle = _('(in %s v%s)') % (proj, version)
+        uri = (_relative_path(Path(), Path(node['refdoc']).parent) / uri).as_posix()
+    if inv_item.project_version:
+        reftitle = _('(in %s v%s)') % (inv_item.project_name, inv_item.project_version)
     else:
-        reftitle = _('(in %s)') % (proj,)
+        reftitle = _('(in %s)') % (inv_item.project_name,)
+
     newnode = nodes.reference('', '', internal=False, refuri=uri, reftitle=reftitle)
     if node.get('refexplicit'):
         # use whatever title was given
         newnode.append(contnode)
-    elif dispname == '-' or (domain.name == 'std' and node['reftype'] == 'keyword'):
+    elif inv_item.display_name == '-' or (
+        domain_name == 'std' and node['reftype'] == 'keyword'
+    ):
         # use whatever title was given, but strip prefix
         title = contnode.astext()
         if inv_name is not None and title.startswith(inv_name + ':'):
@@ -64,14 +69,14 @@ def _create_element_from_result(
             newnode.append(contnode)
     else:
         # else use the given display name (used for :ref:)
-        newnode.append(contnode.__class__(dispname, dispname))
+        newnode.append(contnode.__class__(inv_item.display_name, inv_item.display_name))
     return newnode
 
 
 def _resolve_reference_in_domain_by_target(
     inv_name: InventoryName | None,
     inventory: Inventory,
-    domain: Domain,
+    domain_name: str,
     objtypes: Iterable[str],
     target: str,
     node: pending_xref,
@@ -128,46 +133,47 @@ def _resolve_reference_in_domain_by_target(
             # This is a fix for terms specifically, but potentially should apply to
             # other types.
             continue
-        return _create_element_from_result(domain, inv_name, data, node, contnode)
+        return _create_element_from_result(domain_name, inv_name, data, node, contnode)
     return None
 
 
 def _resolve_reference_in_domain(
-    env: BuildEnvironment,
     inv_name: InventoryName | None,
     inventory: Inventory,
     honor_disabled_refs: bool,
+    disabled_reftypes: Set[str],
     domain: Domain,
     objtypes: Iterable[str],
     node: pending_xref,
     contnode: TextElement,
 ) -> nodes.reference | None:
-    obj_types: dict[str, None] = {}.fromkeys(objtypes)
+    domain_name = domain.name
+    obj_types: dict[str, None] = dict.fromkeys(objtypes)
 
     # we adjust the object types for backwards compatibility
-    if domain.name == 'std' and 'cmdoption' in obj_types:
+    if domain_name == 'std' and 'cmdoption' in obj_types:
         # cmdoptions were stored as std:option until Sphinx 1.6
         obj_types['option'] = None
-    if domain.name == 'py' and 'attribute' in obj_types:
+    if domain_name == 'py' and 'attribute' in obj_types:
         # properties are stored as py:method since Sphinx 2.1
         obj_types['method'] = None
 
     # the inventory contains domain:type as objtype
-    domain_name = domain.name
     obj_types = {f'{domain_name}:{obj_type}': None for obj_type in obj_types}
 
     # now that the objtypes list is complete we can remove the disabled ones
     if honor_disabled_refs:
-        disabled = set(env.config.intersphinx_disabled_reftypes)
         obj_types = {
-            obj_type: None for obj_type in obj_types if obj_type not in disabled
+            obj_type: None
+            for obj_type in obj_types
+            if obj_type not in disabled_reftypes
         }
 
     objtypes = [*obj_types.keys()]
 
     # without qualification
     res = _resolve_reference_in_domain_by_target(
-        inv_name, inventory, domain, objtypes, node['reftarget'], node, contnode
+        inv_name, inventory, domain_name, objtypes, node['reftarget'], node, contnode
     )
     if res is not None:
         return res
@@ -177,39 +183,36 @@ def _resolve_reference_in_domain(
     if full_qualified_name is None:
         return None
     return _resolve_reference_in_domain_by_target(
-        inv_name, inventory, domain, objtypes, full_qualified_name, node, contnode
+        inv_name, inventory, domain_name, objtypes, full_qualified_name, node, contnode
     )
 
 
 def _resolve_reference(
-    env: BuildEnvironment,
     inv_name: InventoryName | None,
+    domains: _DomainsContainer,
     inventory: Inventory,
     honor_disabled_refs: bool,
+    disabled_reftypes: Set[str],
     node: pending_xref,
     contnode: TextElement,
 ) -> nodes.reference | None:
     # disabling should only be done if no inventory is given
     honor_disabled_refs = honor_disabled_refs and inv_name is None
-    intersphinx_disabled_reftypes = env.config.intersphinx_disabled_reftypes
 
-    if honor_disabled_refs and '*' in intersphinx_disabled_reftypes:
+    if honor_disabled_refs and '*' in disabled_reftypes:
         return None
 
     typ = node['reftype']
     if typ == 'any':
-        for domain in env.domains.sorted():
-            if (
-                honor_disabled_refs
-                and f'{domain.name}:*' in intersphinx_disabled_reftypes
-            ):
+        for domain in domains.sorted():
+            if honor_disabled_refs and f'{domain.name}:*' in disabled_reftypes:
                 continue
             objtypes: Iterable[str] = domain.object_types.keys()
             res = _resolve_reference_in_domain(
-                env,
                 inv_name,
                 inventory,
                 honor_disabled_refs,
+                disabled_reftypes,
                 domain,
                 objtypes,
                 node,
@@ -223,17 +226,22 @@ def _resolve_reference(
         if not domain_name:
             # only objects in domains are in the inventory
             return None
-        if honor_disabled_refs and f'{domain_name}:*' in intersphinx_disabled_reftypes:
+        if honor_disabled_refs and f'{domain_name}:*' in disabled_reftypes:
             return None
-        domain = env.get_domain(domain_name)
+        try:
+            domain = domains[domain_name]
+        except KeyError as exc:
+            msg = __('Domain %r is not registered') % domain_name
+            raise ExtensionError(msg) from exc
+
         objtypes = domain.objtypes_for_role(typ) or ()
         if not objtypes:
             return None
         return _resolve_reference_in_domain(
-            env,
             inv_name,
             inventory,
             honor_disabled_refs,
+            disabled_reftypes,
             domain,
             objtypes,
             node,
@@ -259,10 +267,11 @@ def resolve_reference_in_inventory(
     """
     assert inventory_exists(env, inv_name)
     return _resolve_reference(
-        env,
         inv_name,
+        env.domains,
         InventoryAdapter(env).named_inventory[inv_name],
         False,
+        frozenset(env.config.intersphinx_disabled_reftypes),
         node,
         contnode,
     )
@@ -279,10 +288,11 @@ def resolve_reference_any_inventory(
     Resolution is tried with the target as is in any inventory.
     """
     return _resolve_reference(
-        env,
         None,
+        env.domains,
         InventoryAdapter(env).main_inventory,
         honor_disabled_refs,
+        frozenset(env.config.intersphinx_disabled_reftypes),
         node,
         contnode,
     )
@@ -295,9 +305,11 @@ def resolve_reference_detect_inventory(
 
     Resolution is tried first with the target as is in any inventory.
     If this does not succeed, then the target is split by the first ``:``,
-    to form ``inv_name:newtarget``. If ``inv_name`` is a named inventory, then resolution
+    to form ``inv_name:new_target``. If ``inv_name`` is a named inventory, then resolution
     is tried in that inventory with the new target.
     """
+    resolve_self = env.config.intersphinx_resolve_self
+
     # ordinary direct lookup, use data as is
     res = resolve_reference_any_inventory(env, True, node, contnode)
     if res is not None:
@@ -307,10 +319,18 @@ def resolve_reference_detect_inventory(
     target = node['reftarget']
     if ':' not in target:
         return None
-    inv_name, newtarget = target.split(':', 1)
+    inv_name, _, new_target = target.partition(':')
+
+    # check if the target is self-referential
+    self_referential = bool(resolve_self) and resolve_self == inv_name
+    if self_referential:
+        node['reftarget'] = new_target
+        node['intersphinx_self_referential'] = True
+        return None
+
     if not inventory_exists(env, inv_name):
         return None
-    node['reftarget'] = newtarget
+    node['reftarget'] = new_target
     res_inv = resolve_reference_in_inventory(env, inv_name, node, contnode)
     node['reftarget'] = target
     return res_inv
@@ -354,11 +374,16 @@ class IntersphinxRole(SphinxRole):
     def run(self) -> tuple[list[Node], list[system_message]]:
         assert self.name == self.orig_name.lower()
         inventory, name_suffix = self.get_inventory_and_name_suffix(self.orig_name)
-        if inventory and not inventory_exists(self.env, inventory):
-            self._emit_warning(
-                __('inventory for external cross-reference not found: %r'), inventory
-            )
-            return [], []
+        resolve_self = self.env.config.intersphinx_resolve_self
+        self_referential = bool(resolve_self) and resolve_self == inventory
+
+        if not self_referential:
+            if inventory and not inventory_exists(self.env, inventory):
+                self._emit_warning(
+                    __('inventory for external cross-reference not found: %r'),
+                    inventory,
+                )
+                return [], []
 
         domain_name, role_name = self._get_domain_role(name_suffix)
 
@@ -397,27 +422,30 @@ class IntersphinxRole(SphinxRole):
         else:
             # the user did not specify a domain,
             # so we check first the default (if available) then standard domains
-            domains: list[Domain] = []
-            if default_domain := self.env.temp_data.get('default_domain'):
-                domains.append(default_domain)
-            if (
-                std_domain := self.env.domains.standard_domain
-            ) is not None and std_domain not in domains:
-                domains.append(std_domain)
+            default_domain = self.env.current_document.default_domain
+            std_domain = self.env.domains.standard_domain
+            domains: Sequence[Domain]
+            if default_domain is None or std_domain == default_domain:
+                domains = (std_domain,)
+            else:
+                domains = (default_domain, std_domain)
 
             role_func = None
             for domain in domains:
-                if (role_func := domain.roles.get(role_name)) is not None:
+                role_func = domain.roles.get(role_name)
+                if role_func is not None:
                     domain_name = domain.name
                     break
 
             if role_func is None or domain_name is None:
-                domains_str = self._concat_strings(d.name for d in domains)
+                domains_str = self._concat_strings(domain.name for domain in domains)
                 msg = 'role for external cross-reference not found in domains %s: %r'
-                possible_roles: set[str] = set()
-                for d in domains:
-                    if o := d.object_types.get(role_name):
-                        possible_roles.update(f'{d.name}:{r}' for r in o.roles)
+                possible_roles: set[str] = {
+                    f'{domain.name}:{r}'
+                    for domain in domains
+                    if (object_types := domain.object_types.get(role_name))
+                    for r in object_types.roles
+                }
                 if possible_roles:
                     msg = f'{msg} (perhaps you meant one of: %s)'
                     self._emit_warning(
@@ -440,10 +468,14 @@ class IntersphinxRole(SphinxRole):
             self.content,
         )
 
-        for node in result:
-            if isinstance(node, pending_xref):
-                node['intersphinx'] = True
-                node['inventory'] = inventory
+        if not self_referential:
+            # We do the intersphinx resolution by inserting our
+            # 'intersphinx' and 'inventory' attributes into the nodes.
+            # Only do this when it is an external reference.
+            for node in result:
+                if isinstance(node, pending_xref):
+                    node['intersphinx'] = True
+                    node['inventory'] = inventory
 
         return result, messages
 
@@ -505,20 +537,21 @@ class IntersphinxRole(SphinxRole):
         names = name.split(':')
         if len(names) == 1:
             # role
-            default_domain = self.env.temp_data.get('default_domain')
-            domain = default_domain.name if default_domain else None
+            if (domain := self.env.current_document.default_domain) is not None:
+                domain_name = domain.name
+            else:
+                domain_name = None
             role = names[0]
         elif len(names) == 2:
             # domain:role:
-            domain = names[0]
-            role = names[1]
+            domain_name, role = names
         else:
             return None
 
-        if domain and self.is_existent_role(domain, role):
-            return (domain, role)
+        if domain_name and self.is_existent_role(domain_name, role):
+            return domain_name, role
         elif self.is_existent_role('std', role):
-            return ('std', role)
+            return 'std', role
         else:
             return None
 
@@ -527,10 +560,11 @@ class IntersphinxRole(SphinxRole):
             __name__, f'{self.__class__.__name__}.is_existent_role', '', remove=(9, 0)
         )
         try:
-            domain = self.env.get_domain(domain_name)
-            return role_name in domain.roles
-        except ExtensionError:
+            domain = self.env.domains[domain_name]
+        except KeyError:
             return False
+        else:
+            return role_name in domain.roles
 
     def invoke_role(
         self, role: tuple[str, str]
@@ -569,7 +603,7 @@ class IntersphinxRoleResolver(ReferencesResolver):
         for node in self.document.findall(pending_xref):
             if 'intersphinx' not in node:
                 continue
-            contnode = cast(nodes.TextElement, node[0].deepcopy())
+            contnode = cast('nodes.TextElement', node[0].deepcopy())
             inv_name = node['inventory']
             if inv_name is not None:
                 assert inventory_exists(self.env, inv_name)

sphinx/ext/intersphinx/_shared.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Final, NoReturn
+from typing import TYPE_CHECKING
 
 from sphinx.util import logging
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from typing import TypeAlias
+    from typing import Any, Final, NoReturn, TypeAlias
 
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import Inventory

sphinx/ext/linkcode.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from types import FunctionType, NoneType
 from typing import TYPE_CHECKING
 
 from docutils import nodes
@@ -18,12 +19,29 @@ if TYPE_CHECKING:
     from sphinx.util.typing import ExtensionMetadata
 
 
+_DOMAIN_KEYS = {
+    'py': ['module', 'fullname'],
+    'c': ['names'],
+    'cpp': ['names'],
+    'js': ['object', 'fullname'],
+}
+
+
+def add_linkcode_domain(domain: str, keys: list[str], override: bool = False) -> None:
+    """Register a new list of keys to use for a domain.
+
+    .. versionadded:: 8.2
+    """
+    if override or domain not in _DOMAIN_KEYS:
+        _DOMAIN_KEYS[domain] = list(keys)
+
+
 class LinkcodeError(SphinxError):
-    category = "linkcode error"
+    category = 'linkcode error'
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
-    env = app.builder.env
+    env = app.env
 
     resolve_target = getattr(env.config, 'linkcode_resolve', None)
     if not callable(env.config.linkcode_resolve):
@@ -37,13 +55,6 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
     # ``supported_linkcode`` attribute.
     node_only_expr = getattr(app.builder, 'supported_linkcode', 'html')
 
-    domain_keys = {
-        'py': ['module', 'fullname'],
-        'c': ['names'],
-        'cpp': ['names'],
-        'js': ['object', 'fullname'],
-    }
-
     for objnode in list(doctree.findall(addnodes.desc)):
         domain = objnode.get('domain')
         uris: set[str] = set()
@@ -53,7 +64,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
 
             # Convert signode to a specified format
             info = {}
-            for key in domain_keys.get(domain, []):
+            for key in _DOMAIN_KEYS.get(domain, ()):
                 value = signode.get(key)
                 if not value:
                     value = ''
@@ -80,5 +91,10 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('doctree-read', doctree_read)
-    app.add_config_value('linkcode_resolve', None, '')
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    app.add_config_value(
+        'linkcode_resolve', None, '', types=frozenset({FunctionType, NoneType})
+    )
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }

sphinx/ext/mathjax.py

@@ -8,18 +8,21 @@ This requires the MathJax JavaScript library on your webserver/computer.
 from __future__ import annotations
 
 import json
-from typing import TYPE_CHECKING, Any, cast
+from types import NoneType
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
 
 import sphinx
-from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.errors import ExtensionError
 from sphinx.locale import _
 from sphinx.util.math import get_node_equation_number
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from sphinx.application import Sphinx
+    from sphinx.builders.html import StandaloneHTMLBuilder
     from sphinx.util.typing import ExtensionMetadata
     from sphinx.writers.html5 import HTML5Translator
 
@@ -31,16 +34,21 @@ logger = sphinx.util.logging.getLogger(__name__)
 
 
 def html_visit_math(self: HTML5Translator, node: nodes.math) -> None:
-    self.body.append(self.starttag(node, 'span', '', CLASS='math notranslate nohighlight'))
-    self.body.append(self.builder.config.mathjax_inline[0] +
-                     self.encode(node.astext()) +
-                     self.builder.config.mathjax_inline[1] + '</span>')
+    self.body.append(
+        self.starttag(node, 'span', '', CLASS='math notranslate nohighlight')
+    )
+    self.body.append(
+        self.builder.config.mathjax_inline[0]
+        + self.encode(node.astext())
+        + self.builder.config.mathjax_inline[1]
+        + '</span>'
+    )
     raise nodes.SkipNode
 
 
 def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> None:
     self.body.append(self.starttag(node, 'div', CLASS='math notranslate nohighlight'))
-    if node['nowrap']:
+    if node.get('no-wrap', node.get('nowrap', False)):
         self.body.append(self.encode(node.astext()))
         self.body.append('</div>')
         raise nodes.SkipNode
@@ -70,26 +78,31 @@ def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> Non
     raise nodes.SkipNode
 
 
-def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any],
-                    event_arg: Any) -> None:
-    if (
-        app.builder.format != 'html' or
-        app.builder.math_renderer_name != 'mathjax'  # type: ignore[attr-defined]
-    ):
+def install_mathjax(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: dict[str, Any],
+    event_arg: Any,
+) -> None:
+    if app.builder.format != 'html':
+        return
+    if app.builder.math_renderer_name != 'mathjax':  # type: ignore[attr-defined]
         return
     if not app.config.mathjax_path:
         msg = 'mathjax_path config value must be set for the mathjax extension to work'
         raise ExtensionError(msg)
 
-    domain = app.env.domains.math_domain
-    builder = cast(StandaloneHTMLBuilder, app.builder)
-    if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename):
+    builder = cast('StandaloneHTMLBuilder', app.builder)
+    page_has_equations = context.get('has_maths_elements', False)
+    if app.registry.html_assets_policy == 'always' or page_has_equations:
         # Enable mathjax only if equations exists
         if app.config.mathjax2_config:
             if app.config.mathjax_path == MATHJAX_URL:
                 logger.warning(
                     'mathjax_config/mathjax2_config does not work '
-                    'for the current MathJax version, use mathjax3_config instead')
+                    'for the current MathJax version, use mathjax3_config instead'
+                )
             body = 'MathJax.Hub.Config(%s)' % json.dumps(app.config.mathjax2_config)
             builder.add_js_file('', type='text/x-mathjax-config', body=body)
         if app.config.mathjax3_config:
@@ -110,17 +123,35 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: dict
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_html_math_renderer('mathjax',
-                               (html_visit_math, None),
-                               (html_visit_displaymath, None))
-
-    app.add_config_value('mathjax_path', MATHJAX_URL, 'html')
-    app.add_config_value('mathjax_options', {}, 'html')
-    app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
-    app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')
-    app.add_config_value('mathjax_config', None, 'html')
-    app.add_config_value('mathjax2_config', lambda c: c.mathjax_config, 'html')
-    app.add_config_value('mathjax3_config', None, 'html')
+    app.add_html_math_renderer(
+        'mathjax',
+        inline_renderers=(html_visit_math, None),
+        block_renderers=(html_visit_displaymath, None),
+    )
+
+    app.add_config_value('mathjax_path', MATHJAX_URL, 'html', types=frozenset({str}))
+    app.add_config_value('mathjax_options', {}, 'html', types=frozenset({dict}))
+    app.add_config_value(
+        'mathjax_inline', [r'\(', r'\)'], 'html', types=frozenset({list, tuple})
+    )
+    app.add_config_value(
+        'mathjax_display', [r'\[', r'\]'], 'html', types=frozenset({list, tuple})
+    )
+    app.add_config_value(
+        'mathjax_config', None, 'html', types=frozenset({dict, NoneType})
+    )
+    app.add_config_value(
+        'mathjax2_config',
+        lambda c: c.mathjax_config,
+        'html',
+        types=frozenset({dict, NoneType}),
+    )
+    app.add_config_value(
+        'mathjax3_config', None, 'html', types=frozenset({dict, NoneType})
+    )
     app.connect('html-page-context', install_mathjax)
 
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }