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

sphinx/domains/index.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -16,6 +16,7 @@ from sphinx.util.nodes import process_index_entry
 
 if TYPE_CHECKING:
     from collections.abc import Set
+    from typing import Any, ClassVar
 
     from docutils.nodes import Node, system_message
 
@@ -48,21 +49,20 @@ class IndexDomain(Domain):
         """Process a document after it is read by the environment."""
         entries = self.entries.setdefault(env.docname, [])
         for node in list(document.findall(addnodes.index)):
+            node_entries = node['entries']
             try:
-                for (entry_type, value, _target_id, _main, _category_key) in node['entries']:
+                for entry_type, value, _target_id, _main, _category_key in node_entries:
                     split_index_msg(entry_type, value)
             except ValueError as exc:
-                logger.warning(str(exc), location=node)
+                logger.warning(str(exc), location=node, type='index')
                 node.parent.remove(node)
             else:
-                for entry in node['entries']:
+                for entry in node_entries:
                     entries.append(entry)
 
 
 class IndexDirective(SphinxDirective):
-    """
-    Directive to add entries to the index.
-    """
+    """Directive to add entries to the index."""
 
     has_content = False
     required_arguments = 1
@@ -88,7 +88,9 @@ class IndexDirective(SphinxDirective):
         indexnode['inline'] = False
         self.set_source_info(indexnode)
         for entry in arguments:
-            indexnode['entries'].extend(process_index_entry(entry, targetnode['ids'][0]))
+            indexnode['entries'].extend(
+                process_index_entry(entry, targetnode['ids'][0])
+            )
         return [indexnode, targetnode]
 
 

sphinx/domains/javascript.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import contextlib
-from typing import TYPE_CHECKING, Any, ClassVar
+from types import NoneType
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -21,6 +22,7 @@ from sphinx.util.nodes import make_id, make_refnode
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Set
+    from typing import Any, ClassVar
 
     from docutils.nodes import Element, Node
 
@@ -34,9 +36,7 @@ logger = logging.getLogger(__name__)
 
 
 class JSObject(ObjectDescription[tuple[str, str]]):
-    """
-    Description of a JavaScript object.
-    """
+    """Description of a JavaScript object."""
 
     #: If set to ``True`` this object is callable and a `desc_parameterlist` is
     #: added
@@ -100,14 +100,20 @@ class JSObject(ObjectDescription[tuple[str, str]]):
         signode['object'] = prefix
         signode['fullname'] = fullname
 
-        max_len = (self.env.config.javascript_maximum_signature_line_length
-                   or self.env.config.maximum_signature_line_length
-                   or 0)
+        max_len = (
+            self.config.javascript_maximum_signature_line_length
+            or self.config.maximum_signature_line_length
+            or 0
+        )
         multi_line_parameter_list = (
             'single-line-parameter-list' not in self.options
             and (len(sig) > max_len > 0)
         )
 
+        trailing_comma = (
+            self.env.config.javascript_trailing_comma_in_multi_line_signatures
+        )
+
         display_prefix = self.get_display_prefix()
         if display_prefix:
             signode += addnodes.desc_annotation('', '', *display_prefix)
@@ -118,17 +124,22 @@ class JSObject(ObjectDescription[tuple[str, str]]):
         elif mod_name:
             actual_prefix = mod_name
         if actual_prefix:
-            addName = addnodes.desc_addname('', '')
+            add_name = addnodes.desc_addname('', '')
             for p in actual_prefix.split('.'):
-                addName += addnodes.desc_sig_name(p, p)
-                addName += addnodes.desc_sig_punctuation('.', '.')
-            signode += addName
+                add_name += addnodes.desc_sig_name(p, p)
+                add_name += addnodes.desc_sig_punctuation('.', '.')
+            signode += add_name
         signode += addnodes.desc_name('', '', addnodes.desc_sig_name(name, name))
         if self.has_arguments:
             if not arglist:
                 signode += addnodes.desc_parameterlist()
             else:
-                _pseudo_parse_arglist(signode, arglist, multi_line_parameter_list)
+                _pseudo_parse_arglist(
+                    signode,
+                    arglist,
+                    multi_line_parameter_list,
+                    trailing_comma,
+                )
         return fullname, prefix
 
     def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
@@ -142,10 +153,11 @@ class JSObject(ObjectDescription[tuple[str, str]]):
         else:
             return tuple(fullname.split('.'))
 
-    def add_target_and_index(self, name_obj: tuple[str, str], sig: str,
-                             signode: desc_signature) -> None:
-        mod_name = self.env.ref_context.get('js:module')
-        fullname = (mod_name + '.' if mod_name else '') + name_obj[0]
+    def add_target_and_index(
+        self, name_obj: tuple[str, str], sig: str, signode: desc_signature
+    ) -> None:
+        mod_name = self.env.ref_context.get('js:module', '')
+        fullname = (f'{mod_name}.' if mod_name else '') + name_obj[0]
         node_id = make_id(self.env, self.state.document, '', fullname)
         signode['ids'].append(node_id)
         self.state.document.note_explicit_target(signode)
@@ -154,9 +166,14 @@ class JSObject(ObjectDescription[tuple[str, str]]):
         domain.note_object(fullname, self.objtype, node_id, location=signode)
 
         if 'no-index-entry' not in self.options:
-            indextext = self.get_index_text(mod_name, name_obj)  # type: ignore[arg-type]
-            if indextext:
-                self.indexnode['entries'].append(('single', indextext, node_id, '', None))
+            if index_text := self.get_index_text(mod_name, name_obj):
+                self.indexnode['entries'].append((
+                    'single',
+                    index_text,
+                    node_id,
+                    '',
+                    None,
+                ))
 
     def get_index_text(self, objectname: str, name_obj: tuple[str, str]) -> str:
         name, obj = name_obj
@@ -223,14 +240,13 @@ class JSObject(ObjectDescription[tuple[str, str]]):
             with contextlib.suppress(IndexError):
                 objects.pop()
 
-        self.env.ref_context['js:object'] = (objects[-1] if len(objects) > 0
-                                             else None)
+        self.env.ref_context['js:object'] = objects[-1] if len(objects) > 0 else None
 
     def _toc_entry_name(self, sig_node: desc_signature) -> str:
         if not sig_node.get('_toc_parts'):
             return ''
 
-        config = self.env.app.config
+        config = self.config
         objtype = sig_node.parent.get('objtype')
         if config.add_function_parentheses and objtype in {'function', 'method'}:
             parens = '()'
@@ -252,16 +268,32 @@ class JSCallable(JSObject):
     has_arguments = True
 
     doc_field_types = [
-        TypedField('arguments', label=_('Arguments'),
-                   names=('argument', 'arg', 'parameter', 'param'),
-                   typerolename='func', typenames=('paramtype', 'type')),
-        GroupedField('errors', label=_('Throws'), rolename='func',
-                     names=('throws', ),
-                     can_collapse=True),
-        Field('returnvalue', label=_('Returns'), has_arg=False,
-              names=('returns', 'return')),
-        Field('returntype', label=_('Return type'), has_arg=False,
-              names=('rtype',)),
+        TypedField(
+            'arguments',
+            label=_('Arguments'),
+            names=('argument', 'arg', 'parameter', 'param'),
+            typerolename='func',
+            typenames=('paramtype', 'type'),
+        ),
+        GroupedField(
+            'errors',
+            label=_('Throws'),
+            rolename='func',
+            names=('throws',),
+            can_collapse=True,
+        ),
+        Field(
+            'returnvalue',
+            label=_('Returns'),
+            has_arg=False,
+            names=('returns', 'return'),
+        ),
+        Field(
+            'returntype',
+            label=_('Return type'),
+            has_arg=False,
+            names=('rtype',),
+        ),
     ]
 
 
@@ -271,13 +303,14 @@ class JSConstructor(JSCallable):
     allow_nesting = True
 
     def get_display_prefix(self) -> list[Node]:
-        return [addnodes.desc_sig_keyword('class', 'class'),
-                addnodes.desc_sig_space()]
+        return [
+            addnodes.desc_sig_keyword('class', 'class'),
+            addnodes.desc_sig_space(),
+        ]
 
 
 class JSModule(SphinxDirective):
-    """
-    Directive to mark description of a new JavaScript module.
+    """Directive to mark description of a new JavaScript module.
 
     This directive specifies the module name that will be used by objects that
     follow this directive.
@@ -300,6 +333,7 @@ class JSModule(SphinxDirective):
     final_argument_whitespace = False
     option_spec: ClassVar[OptionSpec] = {
         'no-index': directives.flag,
+        'no-index-entry': directives.flag,
         'no-contents-entry': directives.flag,
         'no-typesetting': directives.flag,
         'noindex': directives.flag,
@@ -324,16 +358,20 @@ class JSModule(SphinxDirective):
             domain = self.env.domains.javascript_domain
 
             node_id = make_id(self.env, self.state.document, 'module', mod_name)
-            domain.note_module(mod_name, node_id)
+            domain.note_module(modname=mod_name, node_id=node_id)
             # Make a duplicate entry in 'objects' to facilitate searching for
             # the module in JavaScriptDomain.find_obj()
-            domain.note_object(mod_name, 'module', node_id,
-                               location=(self.env.docname, self.lineno))
+            domain.note_object(
+                mod_name, 'module', node_id, location=(self.env.docname, self.lineno)
+            )
 
             # The node order is: index node first, then target node
-            indextext = _('%s (module)') % mod_name
-            inode = addnodes.index(entries=[('single', indextext, node_id, '', None)])
-            ret.append(inode)
+            if 'no-index-entry' not in self.options:
+                index_text = _('%s (module)') % mod_name
+                inode = addnodes.index(
+                    entries=[('single', index_text, node_id, '', None)]
+                )
+                ret.append(inode)
             target = nodes.target('', '', ids=[node_id], ismod=True)
             self.state.document.note_explicit_target(target)
             ret.append(target)
@@ -342,8 +380,14 @@ class JSModule(SphinxDirective):
 
 
 class JSXRefRole(XRefRole):
-    def process_link(self, env: BuildEnvironment, refnode: Element,
-                     has_explicit_title: bool, title: str, target: str) -> tuple[str, str]:
+    def process_link(
+        self,
+        env: BuildEnvironment,
+        refnode: Element,
+        has_explicit_title: bool,
+        title: str,
+        target: str,
+    ) -> tuple[str, str]:
         # basically what sphinx.domains.python.PyXRefRole does
         refnode['js:object'] = env.ref_context.get('js:object')
         refnode['js:module'] = env.ref_context.get('js:module')
@@ -354,7 +398,7 @@ class JSXRefRole(XRefRole):
                 title = title[1:]
                 dot = title.rfind('.')
                 if dot != -1:
-                    title = title[dot + 1:]
+                    title = title[dot + 1 :]
         if target[0:1] == '.':
             target = target[1:]
             refnode['refspecific'] = True
@@ -368,28 +412,28 @@ class JavaScriptDomain(Domain):
     label = 'JavaScript'
     # if you add a new object type make sure to edit JSObject.get_index_string
     object_types = {
-        'function':  ObjType(_('function'),  'func'),
-        'method':    ObjType(_('method'),    'meth'),
-        'class':     ObjType(_('class'),     'class'),
-        'data':      ObjType(_('data'),      'data'),
+        'function': ObjType(_('function'), 'func'),
+        'method': ObjType(_('method'), 'meth'),
+        'class': ObjType(_('class'), 'class'),
+        'data': ObjType(_('data'), 'data'),
         'attribute': ObjType(_('attribute'), 'attr'),
-        'module':    ObjType(_('module'),    'mod'),
+        'module': ObjType(_('module'), 'mod'),
     }
     directives = {
-        'function':  JSCallable,
-        'method':    JSCallable,
-        'class':     JSConstructor,
-        'data':      JSObject,
+        'function': JSCallable,
+        'method': JSCallable,
+        'class': JSConstructor,
+        'data': JSObject,
         'attribute': JSObject,
-        'module':    JSModule,
+        'module': JSModule,
     }
     roles = {
-        'func':  JSXRefRole(fix_parens=True),
-        'meth':  JSXRefRole(fix_parens=True),
+        'func': JSXRefRole(fix_parens=True),
+        'meth': JSXRefRole(fix_parens=True),
         'class': JSXRefRole(fix_parens=True),
-        'data':  JSXRefRole(),
-        'attr':  JSXRefRole(),
-        'mod':   JSXRefRole(),
+        'data': JSXRefRole(),
+        'attr': JSXRefRole(),
+        'mod': JSXRefRole(),
     }
     initial_data: dict[str, dict[str, tuple[str, str]]] = {
         'objects': {},  # fullname -> docname, node_id, objtype
@@ -398,14 +442,22 @@ class JavaScriptDomain(Domain):
 
     @property
     def objects(self) -> dict[str, tuple[str, str, str]]:
-        return self.data.setdefault('objects', {})  # fullname -> docname, node_id, objtype
+        # fullname -> docname, node_id, objtype
+        return self.data.setdefault('objects', {})
 
-    def note_object(self, fullname: str, objtype: str, node_id: str,
-                    location: Any = None) -> None:
+    def note_object(
+        self, fullname: str, objtype: str, node_id: str, location: Any = None
+    ) -> None:
         if fullname in self.objects:
             docname = self.objects[fullname][0]
-            logger.warning(__('duplicate %s description of %s, other %s in %s'),
-                           objtype, fullname, objtype, docname, location=location)
+            logger.warning(
+                __('duplicate %s description of %s, other %s in %s'),
+                objtype,
+                fullname,
+                objtype,
+                docname,
+                location=location,
+            )
         self.objects[fullname] = (self.env.docname, node_id, objtype)
 
     @property
@@ -464,9 +516,16 @@ class JavaScriptDomain(Domain):
 
         return newname, object_
 
-    def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                     typ: str, target: str, node: pending_xref, contnode: Element,
-                     ) -> Element | None:
+    def resolve_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         mod_name = node.get('js:module')
         prefix = node.get('js:object')
         searchorder = 1 if node.hasattr('refspecific') else 0
@@ -475,16 +534,26 @@ class JavaScriptDomain(Domain):
             return None
         return make_refnode(builder, fromdocname, obj[0], obj[1], contnode, name)
 
-    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                         target: str, node: pending_xref, contnode: Element,
-                         ) -> list[tuple[str, Element]]:
+    def resolve_any_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> list[tuple[str, nodes.reference]]:
         mod_name = node.get('js:module')
         prefix = node.get('js:object')
         name, obj = self.find_obj(env, mod_name, prefix, target, None, 1)
         if not obj:
             return []
-        return [('js:' + self.role_for_objtype(obj[2]),  # type: ignore[operator]
-                 make_refnode(builder, fromdocname, obj[0], obj[1], contnode, name))]
+        return [
+            (
+                f'js:{self.role_for_objtype(obj[2])}',
+                make_refnode(builder, fromdocname, obj[0], obj[1], contnode, name),
+            )
+        ]
 
     def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
         for refname, (docname, node_id, typ) in list(self.objects.items()):
@@ -503,7 +572,16 @@ class JavaScriptDomain(Domain):
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_domain(JavaScriptDomain)
     app.add_config_value(
-        'javascript_maximum_signature_line_length', None, 'env', {int, type(None)},
+        'javascript_maximum_signature_line_length',
+        None,
+        'env',
+        types=frozenset({int, NoneType}),
+    )
+    app.add_config_value(
+        'javascript_trailing_comma_in_multi_line_signatures',
+        True,
+        'env',
+        types=frozenset({bool}),
     )
     return {
         'version': 'builtin',

sphinx/domains/math.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
-from docutils.nodes import Element, Node, make_id, system_message
+from docutils.nodes import make_id
 
 from sphinx.domains import Domain
 from sphinx.locale import __
@@ -15,6 +15,9 @@ from sphinx.util.nodes import make_refnode
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Set
+    from typing import Any
+
+    from docutils.nodes import Element, Node, system_message
 
     from sphinx.addnodes import pending_xref
     from sphinx.application import Sphinx
@@ -27,8 +30,13 @@ logger = logging.getLogger(__name__)
 
 
 class MathReferenceRole(XRefRole):
-    def result_nodes(self, document: nodes.document, env: BuildEnvironment, node: Element,
-                     is_ref: bool) -> tuple[list[Node], list[system_message]]:
+    def result_nodes(
+        self,
+        document: nodes.document,
+        env: BuildEnvironment,
+        node: Element,
+        is_ref: bool,
+    ) -> tuple[list[Node], list[system_message]]:
         node['refdomain'] = 'math'
         return [node], []
 
@@ -41,7 +49,8 @@ class MathDomain(Domain):
 
     initial_data: dict[str, Any] = {
         'objects': {},  # labelid -> (docname, eqno)
-        'has_equations': {},  # docname -> bool
+        # backwards compatibility
+        'has_equations': {},  # https://github.com/sphinx-doc/sphinx/issues/13346
     }
     dangling_warnings = {
         'eq': 'equation not found: %(target)s',
@@ -60,8 +69,12 @@ 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)
 
@@ -71,32 +84,27 @@ class MathDomain(Domain):
         else:
             return None
 
-    def process_doc(self, env: BuildEnvironment, docname: str,
-                    document: nodes.document) -> None:
-        def math_node(node: Node) -> bool:
-            return isinstance(node, nodes.math | nodes.math_block)
-
-        self.data['has_equations'][docname] = any(document.findall(math_node))
-
     def clear_doc(self, docname: str) -> None:
         for equation_id, (doc, _eqno) in list(self.equations.items()):
             if doc == docname:
                 del self.equations[equation_id]
 
-        self.data['has_equations'].pop(docname, None)
-
     def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         for labelid, (doc, eqno) in otherdata['objects'].items():
             if doc in docnames:
                 self.equations[labelid] = (doc, eqno)
 
-        for docname in docnames:
-            self.data['has_equations'][docname] = otherdata['has_equations'][docname]
-
-    def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                     typ: str, target: str, node: pending_xref, contnode: Element,
-                     ) -> Element | None:
-        assert typ in ('eq', 'numref')
+    def resolve_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
+        assert typ in {'eq', 'numref'}
         result = self.equations.get(target)
         if result:
             docname, number = result
@@ -104,7 +112,8 @@ class MathDomain(Domain):
             node_id = make_id('equation-%s' % target)
             if env.config.math_numfig and env.config.numfig:
                 if docname in env.toc_fignumbers:
-                    numbers = env.toc_fignumbers[docname]['displaymath'].get(node_id, ())
+                    toc_dm = env.toc_fignumbers[docname]['displaymath']
+                    numbers = toc_dm.get(node_id, ())
                     eqno = '.'.join(map(str, numbers))
                     eqno = env.config.math_numsep.join(eqno.rsplit('.', 1))
                 else:
@@ -113,21 +122,27 @@ class MathDomain(Domain):
                 eqno = str(number)
 
             try:
-                eqref_format = env.config.math_eqref_format or "({number})"
+                eqref_format = env.config.math_eqref_format or '({number})'
                 title = nodes.Text(eqref_format.format(number=eqno))
             except KeyError as exc:
-                logger.warning(__('Invalid math_eqref_format: %r'), exc,
-                               location=node)
-                title = nodes.Text("(%d)" % number)
-                title = nodes.Text("(%d)" % number)
+                logger.warning(__('Invalid math_eqref_format: %r'), exc, location=node)
+                title = nodes.Text('(%d)' % number)
             return make_refnode(builder, fromdocname, docname, node_id, title)
         else:
             return None
 
-    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                         target: str, node: pending_xref, contnode: Element,
-                         ) -> list[tuple[str, Element]]:
-        refnode = self.resolve_xref(env, fromdocname, builder, 'eq', target, node, contnode)
+    def resolve_any_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> list[tuple[str, nodes.reference]]:
+        refnode = self.resolve_xref(
+            env, fromdocname, builder, 'eq', target, node, contnode
+        )
         if refnode is None:
             return []
         else:
@@ -137,13 +152,8 @@ class MathDomain(Domain):
         return []
 
     def has_equations(self, docname: str | None = None) -> bool:
-        if not docname:
-            return any(self.data['has_equations'].values())
-
-        return (
-            self.data['has_equations'].get(docname, False)
-            or any(map(self.has_equations, self.env.toctree_includes.get(docname, ())))
-        )
+        # retained for backwards compatibility
+        return True
 
 
 def setup(app: Sphinx) -> ExtensionMetadata: