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

sphinx/domains/cpp/_symbol.py

@@ -155,6 +155,9 @@ class Symbol:
         # Do symbol addition after self._children has been initialised.
         self._add_template_and_function_params()
 
+    def __repr__(self) -> str:
+        return f'<Symbol {self.to_string(indent=0)!r}>'
+
     def _fill_empty(self, declaration: ASTDeclaration, docname: str, line: int) -> None:
         self._assert_invariants()
         assert self.declaration is None

sphinx/domains/javascript.py

@@ -17,7 +17,7 @@ from sphinx.roles import XRefRole
 from sphinx.util import logging
 from sphinx.util.docfields import Field, GroupedField, TypedField
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.nodes import make_id, make_refnode, nested_parse_with_titles
+from sphinx.util.nodes import make_id, make_refnode
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
@@ -311,10 +311,7 @@ class JSModule(SphinxDirective):
         self.env.ref_context['js:module'] = mod_name
         no_index = 'no-index' in self.options or 'noindex' in self.options
 
-        content_node: Element = nodes.section()
-        # necessary so that the child nodes get the right source/line set
-        content_node.document = self.state.document
-        nested_parse_with_titles(self.state, self.content, content_node, self.content_offset)
+        content_nodes = self.parse_content_to_nodes(allow_section_headings=True)
 
         ret: list[Node] = []
         if not no_index:
@@ -334,7 +331,7 @@ class JSModule(SphinxDirective):
             target = nodes.target('', '', ids=[node_id], ismod=True)
             self.state.document.note_explicit_target(target)
             ret.append(target)
-        ret.extend(content_node.children)
+        ret.extend(content_nodes)
         return ret
 
 

sphinx/domains/math.py

@@ -60,8 +60,8 @@ class MathDomain(Domain):
     def note_equation(self, docname: str, labelid: str, location: Any = None) -> None:
         if labelid in self.equations:
             other = self.equations[labelid][0]
-            logger.warning(__('duplicate label of equation %s, other instance in %s') %
-                           (labelid, other), location=location)
+            logger.warning(__('duplicate label of equation %s, other instance in %s'),
+                           labelid, other, location=location)
 
         self.equations[labelid] = (docname, self.env.new_serialno('eqno') + 1)
 
@@ -106,6 +106,7 @@ class MathDomain(Domain):
                 if docname in env.toc_fignumbers:
                     numbers = env.toc_fignumbers[docname]['displaymath'].get(node_id, ())
                     eqno = '.'.join(map(str, numbers))
+                    eqno = env.config.math_numsep.join(eqno.rsplit('.', 1))
                 else:
                     eqno = ''
             else:

sphinx/domains/python/__init__.py

@@ -22,7 +22,6 @@ from sphinx.util.nodes import (
     find_pending_xref_condition,
     make_id,
     make_refnode,
-    nested_parse_with_titles,
 )
 
 if TYPE_CHECKING:
@@ -47,6 +46,7 @@ from sphinx.domains.python._object import (  # NoQA: F401
     PyGroupedField,
     PyTypedField,
     PyXrefMixin,
+    py_sig_re,
 )
 
 logger = logging.getLogger(__name__)
@@ -389,6 +389,45 @@ class PyProperty(PyObject):
         return _('%s (%s property)') % (attrname, clsname)
 
 
+class PyTypeAlias(PyObject):
+    """Description of a type alias."""
+
+    option_spec: ClassVar[OptionSpec] = PyObject.option_spec.copy()
+    option_spec.update({
+        'canonical': directives.unchanged,
+    })
+
+    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
+        return [nodes.Text('type'), addnodes.desc_sig_space()]
+
+    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
+        fullname, prefix = super().handle_signature(sig, signode)
+        if canonical := self.options.get('canonical'):
+            canonical_annotations = _parse_annotation(canonical, self.env)
+            signode += addnodes.desc_annotation(
+                canonical, '',
+                addnodes.desc_sig_space(),
+                addnodes.desc_sig_punctuation('', '='),
+                addnodes.desc_sig_space(),
+                *canonical_annotations,
+            )
+        return fullname, prefix
+
+    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
+        name, cls = name_cls
+        try:
+            clsname, attrname = name.rsplit('.', 1)
+            if modname and self.env.config.add_module_names:
+                clsname = f'{modname}.{clsname}'
+        except ValueError:
+            if modname:
+                return _('%s (in module %s)') % (name, modname)
+            else:
+                return name
+
+        return _('%s (type alias in %s)') % (attrname, clsname)
+
+
 class PyModule(SphinxDirective):
     """
     Directive to mark description of a new module.
@@ -416,10 +455,7 @@ class PyModule(SphinxDirective):
         no_index = 'no-index' in self.options or 'noindex' in self.options
         self.env.ref_context['py:module'] = modname
 
-        content_node: Element = nodes.section()
-        # necessary so that the child nodes get the right source/line set
-        content_node.document = self.state.document
-        nested_parse_with_titles(self.state, self.content, content_node, self.content_offset)
+        content_nodes = self.parse_content_to_nodes(allow_section_headings=True)
 
         ret: list[Node] = []
         if not no_index:
@@ -443,7 +479,7 @@ class PyModule(SphinxDirective):
             # The node order is: index node first, then target node.
             ret.append(inode)
             ret.append(target)
-        ret.extend(content_node.children)
+        ret.extend(content_nodes)
         return ret
 
 
@@ -593,6 +629,7 @@ class PythonDomain(Domain):
         'staticmethod': ObjType(_('static method'), 'meth', 'obj'),
         'attribute':    ObjType(_('attribute'),     'attr', 'obj'),
         'property':     ObjType(_('property'),      'attr', '_prop', 'obj'),
+        'type':         ObjType(_('type alias'),    'type', 'obj'),
         'module':       ObjType(_('module'),        'mod', 'obj'),
     }
 
@@ -606,6 +643,7 @@ class PythonDomain(Domain):
         'staticmethod':    PyStaticMethod,
         'attribute':       PyAttribute,
         'property':        PyProperty,
+        'type':            PyTypeAlias,
         'module':          PyModule,
         'currentmodule':   PyCurrentModule,
         'decorator':       PyDecoratorFunction,
@@ -618,6 +656,7 @@ class PythonDomain(Domain):
         'class': PyXRefRole(),
         'const': PyXRefRole(),
         'attr':  PyXRefRole(),
+        'type':  PyXRefRole(),
         'meth':  PyXRefRole(fix_parens=True),
         'mod':   PyXRefRole(),
         'obj':   PyXRefRole(),

sphinx/domains/python/_object.py

@@ -89,6 +89,10 @@ class PyXrefMixin:
 
         return result
 
+    _delimiters_re = re.compile(
+        r'(\s*[\[\]\(\),](?:\s*o[rf]\s)?\s*|\s+o[rf]\s+|\s*\|\s*|\.\.\.)'
+    )
+
     def make_xrefs(
         self,
         rolename: str,
@@ -100,9 +104,7 @@ class PyXrefMixin:
         inliner: Inliner | None = None,
         location: Node | None = None,
     ) -> list[Node]:
-        delims = r'(\s*[\[\]\(\),](?:\s*o[rf]\s)?\s*|\s+o[rf]\s+|\s*\|\s*|\.\.\.)'
-        delims_re = re.compile(delims)
-        sub_targets = re.split(delims, target)
+        sub_targets = self._delimiters_re.split(target)
 
         split_contnode = bool(contnode and contnode.astext() == target)
 
@@ -112,13 +114,13 @@ class PyXrefMixin:
             if split_contnode:
                 contnode = nodes.Text(sub_target)
 
-            if in_literal or delims_re.match(sub_target):
+            if in_literal or self._delimiters_re.match(sub_target):
                 results.append(contnode or innernode(sub_target, sub_target))  # type: ignore[call-arg]
             else:
                 results.append(self.make_xref(rolename, domain, sub_target,
                                               innernode, contnode, env, inliner, location))
 
-            if sub_target in ('Literal', 'typing.Literal', '~typing.Literal'):
+            if sub_target in {'Literal', 'typing.Literal', '~typing.Literal'}:
                 in_literal = True
 
         return results

sphinx/domains/rst.py

@@ -244,8 +244,8 @@ class ReSTDomain(Domain):
     def note_object(self, objtype: str, name: str, node_id: str, location: Any = None) -> None:
         if (objtype, name) in self.objects:
             docname, node_id = self.objects[objtype, name]
-            logger.warning(__('duplicate description of %s %s, other instance in %s') %
-                           (objtype, name, docname), location=location)
+            logger.warning(__('duplicate description of %s %s, other instance in %s'),
+                           objtype, name, docname, location=location)
 
         self.objects[objtype, name] = (self.env.docname, node_id)
 

sphinx/domains/std/__init__.py

@@ -20,6 +20,7 @@ from sphinx.roles import EmphasizedLiteral, XRefRole
 from sphinx.util import docname_join, logging, ws_re
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import clean_astext, make_id, make_refnode
+from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator
@@ -101,6 +102,76 @@ class EnvVarXRefRole(XRefRole):
         return [indexnode, targetnode, node], []
 
 
+class ConfigurationValue(ObjectDescription[str]):
+    index_template: str = _('%s; configuration value')
+    option_spec: ClassVar[OptionSpec] = {
+        'no-index': directives.flag,
+        'no-index-entry': directives.flag,
+        'no-contents-entry': directives.flag,
+        'no-typesetting': directives.flag,
+        'type': directives.unchanged_required,
+        'default': directives.unchanged_required,
+    }
+
+    def handle_signature(self, sig: str, sig_node: desc_signature) -> str:
+        sig_node.clear()
+        sig_node += addnodes.desc_name(sig, sig)
+        name = ws_re.sub(' ', sig)
+        sig_node['fullname'] = name
+        return name
+
+    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
+        return (sig_node['fullname'],)
+
+    def _toc_entry_name(self, sig_node: desc_signature) -> str:
+        if not sig_node.get('_toc_parts'):
+            return ''
+        name, = sig_node['_toc_parts']
+        return name
+
+    def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
+        node_id = make_id(self.env, self.state.document, self.objtype, name)
+        signode['ids'].append(node_id)
+        self.state.document.note_explicit_target(signode)
+        index_entry = self.index_template % name
+        self.indexnode['entries'].append(('pair', index_entry, node_id, '', None))
+        self.env.domains['std'].note_object(self.objtype, name, node_id, location=signode)
+
+    def transform_content(self, content_node: addnodes.desc_content) -> None:
+        """Insert *type* and *default* as a field list."""
+        field_list = nodes.field_list()
+        if 'type' in self.options:
+            field, msgs = self.format_type(self.options['type'])
+            field_list.append(field)
+            field_list += msgs
+        if 'default' in self.options:
+            field, msgs = self.format_default(self.options['default'])
+            field_list.append(field)
+            field_list += msgs
+        if len(field_list.children) > 0:
+            content_node.insert(0, field_list)
+
+    def format_type(self, type_: str) -> tuple[nodes.field, list[system_message]]:
+        """Formats the ``:type:`` option."""
+        parsed, msgs = self.parse_inline(type_, lineno=self.lineno)
+        field = nodes.field(
+            '',
+            nodes.field_name('', _('Type')),
+            nodes.field_body('', *parsed),
+        )
+        return field, msgs
+
+    def format_default(self, default: str) -> tuple[nodes.field, list[system_message]]:
+        """Formats the ``:default:`` option."""
+        parsed, msgs = self.parse_inline(default, lineno=self.lineno)
+        field = nodes.field(
+            '',
+            nodes.field_name('', _('Default')),
+            nodes.field_body('', *parsed),
+        )
+        return field, msgs
+
+
 class Target(SphinxDirective):
     """
     Generic target for user-defined cross-reference types.
@@ -260,13 +331,18 @@ class OptionXRefRole(XRefRole):
         return title, target
 
 
-def split_term_classifiers(line: str) -> list[str | None]:
+_term_classifiers_re = re.compile(' +: +')
+
+
+def split_term_classifiers(line: str) -> tuple[str, str | None]:
     # split line into a term and classifiers. if no classifier, None is used..
-    parts: list[str | None] = [*re.split(' +: +', line), None]
-    return parts
+    parts = _term_classifiers_re.split(line)
+    term = parts[0]
+    first_classifier = parts[1] if len(parts) >= 2 else None
+    return term, first_classifier
 
 
-def make_glossary_term(env: BuildEnvironment, textnodes: Iterable[Node], index_key: str,
+def make_glossary_term(env: BuildEnvironment, textnodes: Iterable[Node], index_key: str | None,
                        source: str, lineno: int, node_id: str | None, document: nodes.document,
                        ) -> nodes.term:
     # get a text-only representation of the term and register it
@@ -382,15 +458,14 @@ class Glossary(SphinxDirective):
             termnodes: list[Node] = []
             system_messages: list[Node] = []
             for line, source, lineno in terms:
-                parts = split_term_classifiers(line)
+                term_, first_classifier = split_term_classifiers(line)
                 # parse the term with inline markup
                 # classifiers (parts[1:]) will not be shown on doctree
-                textnodes, sysmsg = self.state.inline_text(parts[0],
-                                                           lineno)
+                textnodes, sysmsg = self.parse_inline(term_, lineno=lineno)
 
                 # use first classifier as a index key
                 term = make_glossary_term(self.env, textnodes,
-                                          parts[1], source, lineno,  # type: ignore[arg-type]
+                                          first_classifier, source, lineno,
                                           node_id=None, document=self.state.document)
                 term.rawsource = line
                 system_messages.extend(sysmsg)
@@ -398,11 +473,14 @@ class Glossary(SphinxDirective):
 
             termnodes.extend(system_messages)
 
-            defnode = nodes.definition()
             if definition:
-                self.state.nested_parse(definition, definition.items[0][1],
-                                        defnode)
-            termnodes.append(defnode)
+                offset = definition.items[0][1]
+                definition_nodes = nested_parse_to_nodes(
+                    self.state, definition, offset=offset, allow_section_headings=False,
+                )
+            else:
+                definition_nodes = []
+            termnodes.append(nodes.definition('', *definition_nodes))
             items.append(nodes.definition_list_item('', *termnodes))
 
         dlist = nodes.definition_list('', *items)
@@ -519,6 +597,7 @@ class StandardDomain(Domain):
         'token': ObjType(_('grammar token'), 'token', searchprio=-1),
         'label': ObjType(_('reference label'), 'ref', 'keyword',
                          searchprio=-1),
+        'confval': ObjType('configuration value', 'confval'),
         'envvar': ObjType(_('environment variable'), 'envvar'),
         'cmdoption': ObjType(_('program option'), 'option'),
         'doc': ObjType(_('document'), 'doc', searchprio=-1),
@@ -528,12 +607,14 @@ class StandardDomain(Domain):
         'program': Program,
         'cmdoption': Cmdoption,  # old name for backwards compatibility
         'option': Cmdoption,
+        'confval': ConfigurationValue,
         'envvar': EnvVar,
         'glossary': Glossary,
         'productionlist': ProductionList,
     }
     roles: dict[str, RoleFunction | XRefRole] = {
         'option':  OptionXRefRole(warn_dangling=True),
+        'confval': XRefRole(warn_dangling=True),
         'envvar':  EnvVarXRefRole(),
         # links to tokens in grammar productions
         'token':   TokenXRefRole(),
@@ -921,7 +1002,7 @@ class StandardDomain(Domain):
             # * :option:`-foo=bar`
             # * :option:`-foo[=bar]`
             # * :option:`-foo bar`
-            for needle in {'=', '[=', ' '}:
+            for needle in ('=', '[=', ' '):
                 if needle in target:
                     stem, _, _ = target.partition(needle)
                     docname, labelid = self.progoptions.get((progname, stem), ('', ''))
@@ -1110,7 +1191,7 @@ def warn_missing_reference(app: Sphinx, domain: Domain, node: pending_xref,
         else:
             msg = __('Failed to create a cross reference. A title or caption not found: %r')
 
-        logger.warning(msg % target, location=node, type='ref', subtype=node['reftype'])
+        logger.warning(msg, target, location=node, type='ref', subtype=node['reftype'])
         return True
 
 

sphinx/environment/__init__.py

@@ -28,6 +28,7 @@ if TYPE_CHECKING:
 
     from docutils import nodes
     from docutils.nodes import Node
+    from docutils.parsers import Parser
 
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
@@ -74,7 +75,7 @@ CONFIG_CHANGED_REASON = {
 }
 
 
-versioning_conditions: dict[str, bool | Callable] = {
+versioning_conditions: dict[str, Literal[False] | Callable[[Node], bool]] = {
     'none': False,
     'text': is_translatable,
 }
@@ -158,7 +159,7 @@ class BuildEnvironment:
         self.version: dict[str, int] = app.registry.get_envversion(app)
 
         # the method of doctree versioning; see set_versioning_method
-        self.versioning_condition: bool | Callable | None = None
+        self.versioning_condition: Literal[False] | Callable[[Node], bool] | None = None
         self.versioning_compare: bool | None = None
 
         # all the registered domains, set by the application
@@ -183,11 +184,21 @@ class BuildEnvironment:
         # docnames to re-read unconditionally on next build
         self.reread_always: set[str] = set()
 
-        # docname -> pickled doctree
         self._pickled_doctree_cache: dict[str, bytes] = {}
+        """In-memory cache for reading pickled doctrees from disk.
+        docname -> pickled doctree
+
+        This cache is used in the ``get_doctree`` method to avoid reading the
+        doctree from disk multiple times.
+        """
 
-        # docname -> doctree
         self._write_doc_doctree_cache: dict[str, nodes.document] = {}
+        """In-memory cache for unpickling doctrees from disk.
+        docname -> doctree
+
+        Items are added in ``Builder.write_doctree``, during the read phase,
+        then used only in the ``get_and_resolve_doctree`` method.
+        """
 
         # File metadata
         # docname -> dict of metadata items
@@ -222,7 +233,7 @@ class BuildEnvironment:
 
         # domain-specific inventories, here to be pickled
         # domainname -> domain-specific dict
-        self.domaindata: dict[str, dict] = {}
+        self.domaindata: dict[str, dict[str, Any]] = {}
 
         # these map absolute path -> (docnames, unique filename)
         self.images: FilenameUniqDict = FilenameUniqDict()
@@ -242,7 +253,7 @@ class BuildEnvironment:
         # search index data
 
         # docname -> title
-        self._search_index_titles: dict[str, str] = {}
+        self._search_index_titles: dict[str, str | None] = {}
         # docname -> filename
         self._search_index_filenames: dict[str, str] = {}
         # stemmed words -> set(docname)
@@ -250,7 +261,7 @@ class BuildEnvironment:
         # stemmed words in titles -> set(docname)
         self._search_index_title_mapping: dict[str, set[str]] = {}
         # docname -> all titles in document
-        self._search_index_all_titles: dict[str, list[tuple[str, str]]] = {}
+        self._search_index_all_titles: dict[str, list[tuple[str, str | None]]] = {}
         # docname -> list(index entry)
         self._search_index_index_entries: dict[str, list[tuple[str, str, str]]] = {}
         # objtype -> index
@@ -261,16 +272,18 @@ class BuildEnvironment:
         # set up environment
         self.setup(app)
 
-    def __getstate__(self) -> dict:
+    def __getstate__(self) -> dict[str, Any]:
         """Obtains serializable data for pickling."""
         __dict__ = self.__dict__.copy()
-        __dict__.update(app=None, domains={}, events=None)  # clear unpickable attributes
-        # ensure that upon restoring the state, the most recent pickled files
+        # clear unpickable attributes
+        __dict__.update(app=None, domains={}, events=None)
+        # clear in-memory doctree caches, to reduce memory consumption and
+        # ensure that, upon restoring the state, the most recent pickled files
         # on the disk are used instead of those from a possibly outdated state
-        __dict__.update(_pickled_doctree_cache={})
+        __dict__.update(_pickled_doctree_cache={}, _write_doc_doctree_cache={})
         return __dict__
 
-    def __setstate__(self, state: dict) -> None:
+    def __setstate__(self, state: dict[str, Any]) -> None:
         self.__dict__.update(state)
 
     def setup(self, app: Sphinx) -> None:
@@ -340,7 +353,9 @@ class BuildEnvironment:
         # Allow to disable by 3rd party extension (workaround)
         self.settings.setdefault('smart_quotes', True)
 
-    def set_versioning_method(self, method: str | Callable, compare: bool) -> None:
+    def set_versioning_method(
+        self, method: str | Callable[[Node], bool], compare: bool
+    ) -> None:
         """Set the doctree versioning method for this environment.
 
         Versioning methods are a builder property; only builders with the same
@@ -348,7 +363,7 @@ class BuildEnvironment:
         raise an exception if the user tries to use an environment with an
         incompatible versioning method.
         """
-        condition: bool | Callable
+        condition: Literal[False] | Callable[[Node], bool]
         if callable(method):
             condition = method
         else:
@@ -356,7 +371,7 @@ class BuildEnvironment:
                 raise ValueError('invalid versioning method: %r' % method)
             condition = versioning_conditions[method]
 
-        if self.versioning_condition not in (None, condition):
+        if self.versioning_condition not in {None, condition}:
             raise SphinxError(__('This environment is incompatible with the '
                                  'selected builder, please choose another '
                                  'doctree directory.'))
@@ -549,6 +564,11 @@ class BuildEnvironment:
         """Returns the docname of the document currently being parsed."""
         return self.temp_data['docname']
 
+    @property
+    def parser(self) -> Parser:
+        """Returns the parser being used for to parse the current document."""
+        return self.temp_data['_parser']
+
     def new_serialno(self, category: str = '') -> int:
         """Return a serial number, e.g. for index entry targets.