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

sphinx/config.py

@@ -97,17 +97,19 @@ _OptValidTypes = Union[tuple[()], tuple[type, ...], frozenset[type], ENUM]
 
 
 class _Opt:
-    __slots__ = 'default', 'rebuild', 'valid_types'
+    __slots__ = 'default', 'rebuild', 'valid_types', 'description'
 
     default: Any
     rebuild: _ConfigRebuild
     valid_types: _OptValidTypes
+    description: str
 
     def __init__(
         self,
         default: Any,
         rebuild: _ConfigRebuild,
         valid_types: _OptValidTypes,
+        description: str = '',
     ) -> None:
         """Configuration option type for Sphinx.
 
@@ -120,52 +122,56 @@ class _Opt:
         super().__setattr__('default', default)
         super().__setattr__('rebuild', rebuild)
         super().__setattr__('valid_types', valid_types)
+        super().__setattr__('description', description)
 
     def __repr__(self) -> str:
         return (
             f'{self.__class__.__qualname__}('
             f'default={self.default!r}, '
             f'rebuild={self.rebuild!r}, '
-            f'valid_types={self.valid_types!r})'
+            f'valid_types={self.rebuild!r}, '
+            f'description={self.description!r})'
         )
 
     def __eq__(self, other: object) -> bool:
         if isinstance(other, _Opt):
-            self_tpl = (self.default, self.rebuild, self.valid_types)
-            other_tpl = (other.default, other.rebuild, other.valid_types)
+            self_tpl = (self.default, self.rebuild, self.valid_types, self.description)
+            other_tpl = (other.default, other.rebuild, other.valid_types, self.description)
             return self_tpl == other_tpl
         return NotImplemented
 
     def __lt__(self, other: _Opt) -> bool:
         if self.__class__ is other.__class__:
-            self_tpl = (self.default, self.rebuild, self.valid_types)
-            other_tpl = (other.default, other.rebuild, other.valid_types)
+            self_tpl = (self.default, self.rebuild, self.valid_types, self.description)
+            other_tpl = (other.default, other.rebuild, other.valid_types, self.description)
             return self_tpl > other_tpl
         return NotImplemented
 
     def __hash__(self) -> int:
-        return hash((self.default, self.rebuild, self.valid_types))
+        return hash((self.default, self.rebuild, self.valid_types, self.description))
 
     def __setattr__(self, key: str, value: Any) -> None:
-        if key in {'default', 'rebuild', 'valid_types'}:
+        if key in {'default', 'rebuild', 'valid_types', 'description'}:
             msg = f'{self.__class__.__name__!r} object does not support assignment to {key!r}'
             raise TypeError(msg)
         super().__setattr__(key, value)
 
     def __delattr__(self, key: str) -> None:
-        if key in {'default', 'rebuild', 'valid_types'}:
+        if key in {'default', 'rebuild', 'valid_types', 'description'}:
             msg = f'{self.__class__.__name__!r} object does not support deletion of {key!r}'
             raise TypeError(msg)
         super().__delattr__(key)
 
-    def __getstate__(self) -> tuple[Any, _ConfigRebuild, _OptValidTypes]:
-        return self.default, self.rebuild, self.valid_types
+    def __getstate__(self) -> tuple[Any, _ConfigRebuild, _OptValidTypes, str]:
+        return self.default, self.rebuild, self.valid_types, self.description
 
-    def __setstate__(self, state: tuple[Any, _ConfigRebuild, _OptValidTypes]) -> None:
-        default, rebuild, valid_types = state
+    def __setstate__(
+            self, state: tuple[Any, _ConfigRebuild, _OptValidTypes, str]) -> None:
+        default, rebuild, valid_types, description = state
         super().__setattr__('default', default)
         super().__setattr__('rebuild', rebuild)
         super().__setattr__('valid_types', valid_types)
+        super().__setattr__('description', description)
 
     def __getitem__(self, item: int | slice) -> Any:
         warnings.warn(
@@ -196,11 +202,11 @@ class Config:
 
     config_values: dict[str, _Opt] = {
         # general options
-        'project': _Opt('Python', 'env', ()),
-        'author': _Opt('unknown', 'env', ()),
+        'project': _Opt('Project name not set', 'env', ()),
+        'author': _Opt('Author name not set', 'env', ()),
         'project_copyright': _Opt('', 'html', frozenset((str, tuple, list))),
         'copyright': _Opt(
-            lambda c: c.project_copyright, 'html', frozenset((str, tuple, list))),
+            lambda config: config.project_copyright, 'html', frozenset((str, tuple, list))),
         'version': _Opt('', 'env', ()),
         'release': _Opt('', 'env', ()),
         'today': _Opt('', 'env', ()),
@@ -258,6 +264,7 @@ class Config:
         'math_number_all': _Opt(False, 'env', ()),
         'math_eqref_format': _Opt(None, 'env', frozenset((str,))),
         'math_numfig': _Opt(True, 'env', ()),
+        'math_numsep': _Opt('.', 'env', frozenset((str,))),
         'tls_verify': _Opt(True, 'env', ()),
         'tls_cacerts': _Opt(None, 'env', ()),
         'user_agent': _Opt(None, 'env', frozenset((str,))),
@@ -326,34 +333,33 @@ class Config:
         valid_types = opt.valid_types
         if valid_types == Any:
             return value
-        elif (type(default) is bool
-              or (not isinstance(valid_types, ENUM)
-                  and len(valid_types) == 1 and bool in valid_types)):
+        if (type(default) is bool
+            or (not isinstance(valid_types, ENUM)
+                and len(valid_types) == 1 and bool in valid_types)):
             if isinstance(valid_types, ENUM) or len(valid_types) > 1:
                 # if valid_types are given, and non-bool valid types exist,
                 # return the value without coercing to a Boolean.
                 return value
             # given falsy string from a command line option
             return value not in {'0', ''}
-        elif isinstance(default, dict):
+        if isinstance(default, dict):
             raise ValueError(__('cannot override dictionary config setting %r, '
                                 'ignoring (use %r to set individual elements)') %
                              (name, f'{name}.key=value'))
-        elif isinstance(default, list):
+        if isinstance(default, list):
             return value.split(',')
-        elif isinstance(default, int):
+        if isinstance(default, int):
             try:
                 return int(value)
             except ValueError as exc:
                 raise ValueError(__('invalid number %r for config value %r, ignoring') %
                                  (value, name)) from exc
-        elif callable(default):
+        if callable(default):
             return value
-        elif default is not None and not isinstance(default, str):
-            raise ValueError(__('cannot override config setting %r with unsupported '
-                                'type, ignoring') % name)
-        else:
+        if isinstance(default, str) or default is None:
             return value
+        raise ValueError(__('cannot override config setting %r with unsupported '
+                            'type, ignoring') % name)
 
     @staticmethod
     def pre_init_values() -> None:
@@ -385,6 +391,18 @@ class Config:
             values.append(f"{opt_name}={opt_value!r}")
         return self.__class__.__qualname__ + '(' + ', '.join(values) + ')'
 
+    def __setattr__(self, key: str, value: object) -> None:
+        # Ensure aliases update their counterpart.
+        if key == 'master_doc':
+            super().__setattr__('root_doc', value)
+        elif key == 'root_doc':
+            super().__setattr__('master_doc', value)
+        elif key == 'copyright':
+            super().__setattr__('project_copyright', value)
+        elif key == 'project_copyright':
+            super().__setattr__('copyright', value)
+        super().__setattr__(key, value)
+
     def __getattr__(self, name: str) -> Any:
         if name in self._options:
             # first check command-line overrides
@@ -398,11 +416,12 @@ class Config:
                 except ValueError as exc:
                     logger.warning("%s", exc)
                 else:
-                    self.__dict__[name] = value
+                    self.__setattr__(name, value)
                     return value
             # then check values from 'conf.py'
             if name in self._raw_config:
-                self.__dict__[name] = value = self._raw_config[name]
+                value = self._raw_config[name]
+                self.__setattr__(name, value)
                 return value
             # finally, fall back to the default value
             default = self._options[name].default
@@ -433,7 +452,8 @@ class Config:
             yield ConfigValue(name, getattr(self, name), opt.rebuild)
 
     def add(self, name: str, default: Any, rebuild: _ConfigRebuild,
-            types: type | Collection[type] | ENUM) -> None:
+            types: type | Collection[type] | ENUM,
+            description: str = '') -> None:
         if name in self._options:
             raise ExtensionError(__('Config value %r already present') % name)
 
@@ -443,7 +463,7 @@ class Config:
 
         # standardise valid_types
         valid_types = _validate_valid_types(types)
-        self._options[name] = _Opt(default, rebuild, valid_types)
+        self._options[name] = _Opt(default, rebuild, valid_types, description)
 
     def filter(self, rebuild: Set[_ConfigRebuild]) -> Iterator[ConfigValue]:
         if isinstance(rebuild, str):
@@ -561,10 +581,10 @@ def convert_source_suffix(app: Sphinx, config: Config) -> None:
         #
         # The default filetype is determined on later step.
         # By default, it is considered as restructuredtext.
-        config.source_suffix = {source_suffix: None}  # type: ignore[attr-defined]
+        config.source_suffix = {source_suffix: 'restructuredtext'}
     elif isinstance(source_suffix, (list, tuple)):
         # if list, considers as all of them are default filetype
-        config.source_suffix = dict.fromkeys(source_suffix, None)  # type: ignore[attr-defined]
+        config.source_suffix = dict.fromkeys(source_suffix, 'restructuredtext')
     elif not isinstance(source_suffix, dict):
         logger.warning(__("The config value `source_suffix' expects "
                           "a string, list of strings, or dictionary. "
@@ -580,8 +600,7 @@ def convert_highlight_options(app: Sphinx, config: Config) -> None:
     options = config.highlight_options
     if options and not all(isinstance(v, dict) for v in options.values()):
         # old styled option detected because all values are not dictionary.
-        config.highlight_options = {config.highlight_language:  # type: ignore[attr-defined]
-                                    options}
+        config.highlight_options = {config.highlight_language: options}
 
 
 def init_numfig_format(app: Sphinx, config: Config) -> None:
@@ -593,7 +612,7 @@ def init_numfig_format(app: Sphinx, config: Config) -> None:
 
     # override default labels by configuration
     numfig_format.update(config.numfig_format)
-    config.numfig_format = numfig_format  # type: ignore[attr-defined]
+    config.numfig_format = numfig_format
 
 
 def correct_copyright_year(_app: Sphinx, config: Config) -> None:
@@ -713,7 +732,7 @@ def check_primary_domain(app: Sphinx, config: Config) -> None:
     primary_domain = config.primary_domain
     if primary_domain and not app.registry.has_domain(primary_domain):
         logger.warning(__('primary_domain %r not found, ignored.'), primary_domain)
-        config.primary_domain = None  # type: ignore[attr-defined]
+        config.primary_domain = None
 
 
 def check_root_doc(app: Sphinx, env: BuildEnvironment, added: set[str],
@@ -726,7 +745,7 @@ def check_root_doc(app: Sphinx, env: BuildEnvironment, added: set[str],
             'contents' in app.project.docnames):
         logger.warning(__('Since v2.0, Sphinx uses "index" as root_doc by default. '
                           'Please add "root_doc = \'contents\'" to your conf.py.'))
-        app.config.root_doc = "contents"  # type: ignore[attr-defined]
+        app.config.root_doc = "contents"
 
     return changed
 

sphinx/directives/__init__.py

@@ -13,7 +13,6 @@ from sphinx.addnodes import desc_signature  # NoQA: TCH001
 from sphinx.util import docutils
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.typing import ExtensionMetadata, OptionSpec  # NoQA: TCH001
 
 if TYPE_CHECKING:
@@ -127,7 +126,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
         """
         pass
 
-    def transform_content(self, contentnode: addnodes.desc_content) -> None:
+    def transform_content(self, content_node: addnodes.desc_content) -> None:
         """
         Called after creating the content through nested parsing,
         but before the ``object-description-transform`` event is emitted,
@@ -275,18 +274,17 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
                     # description of the object with this name in this desc block
                     self.add_target_and_index(name, sig, signode)
 
-        contentnode = addnodes.desc_content()
-        node.append(contentnode)
-
         if self.names:
             # needed for association of version{added,changed} directives
             self.env.temp_data['object'] = self.names[0]
         self.before_content()
-        nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
-        self.transform_content(contentnode)
+        content_children = self.parse_content_to_nodes(allow_section_headings=True)
+        content_node = addnodes.desc_content('', *content_children)
+        node.append(content_node)
+        self.transform_content(content_node)
         self.env.app.emit('object-description-transform',
-                          self.domain, self.objtype, contentnode)
-        DocFieldTransformer(self).transform_all(contentnode)
+                          self.domain, self.objtype, content_node)
+        DocFieldTransformer(self).transform_all(content_node)
         self.env.temp_data['object'] = None
         self.after_content()
 

sphinx/directives/code.py

@@ -7,7 +7,6 @@ from typing import TYPE_CHECKING, Any, ClassVar
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from docutils.statemachine import StringList
 
 from sphinx import addnodes
 from sphinx.directives import optional_int
@@ -75,15 +74,13 @@ def container_wrapper(
 ) -> nodes.container:
     container_node = nodes.container('', literal_block=True,
                                      classes=['literal-block-wrapper'])
-    parsed = nodes.Element()
-    directive.state.nested_parse(StringList([caption], source=''),
-                                 directive.content_offset, parsed)
-    if isinstance(parsed[0], nodes.system_message):
-        msg = __('Invalid caption: %s' % parsed[0].astext())
+    parsed = directive.parse_text_to_nodes(caption, offset=directive.content_offset)
+    node = parsed[0]
+    if isinstance(node, nodes.system_message):
+        msg = __('Invalid caption: %s') % node.astext()
         raise ValueError(msg)
-    if isinstance(parsed[0], nodes.Element):
-        caption_node = nodes.caption(parsed[0].rawsource, '',
-                                     *parsed[0].children)
+    if isinstance(node, nodes.Element):
+        caption_node = nodes.caption(node.rawsource, '', *node.children)
         caption_node.source = literal_node.source
         caption_node.line = literal_node.line
         container_node += caption_node
@@ -124,8 +121,8 @@ class CodeBlock(SphinxDirective):
                 nlines = len(self.content)
                 hl_lines = parselinenos(linespec, nlines)
                 if any(i >= nlines for i in hl_lines):
-                    logger.warning(__('line number spec is out of range(1-%d): %r') %
-                                   (nlines, self.options['emphasize-lines']),
+                    logger.warning(__('line number spec is out of range(1-%d): %r'),
+                                   nlines, self.options['emphasize-lines'],
                                    location=location)
 
                 hl_lines = [x + 1 for x in hl_lines if x < nlines]
@@ -274,8 +271,8 @@ class LiteralIncludeReader:
         if linespec:
             linelist = parselinenos(linespec, len(lines))
             if any(i >= len(lines) for i in linelist):
-                logger.warning(__('line number spec is out of range(1-%d): %r') %
-                               (len(lines), linespec), location=location)
+                logger.warning(__('line number spec is out of range(1-%d): %r'),
+                               len(lines), linespec, location=location)
 
             if 'lineno-match' in self.options:
                 # make sure the line list is not "disjoint".
@@ -450,8 +447,8 @@ class LiteralInclude(SphinxDirective):
             if 'emphasize-lines' in self.options:
                 hl_lines = parselinenos(self.options['emphasize-lines'], lines)
                 if any(i >= lines for i in hl_lines):
-                    logger.warning(__('line number spec is out of range(1-%d): %r') %
-                                   (lines, self.options['emphasize-lines']),
+                    logger.warning(__('line number spec is out of range(1-%d): %r'),
+                                   lines, self.options['emphasize-lines'],
                                    location=location)
                 extra_args['hl_lines'] = [x + 1 for x in hl_lines if x < lines]
             extra_args['linenostart'] = reader.lineno_start

sphinx/directives/other.py

@@ -53,6 +53,7 @@ class TocTree(SphinxDirective):
     option_spec = {
         'maxdepth': int,
         'name': directives.unchanged,
+        'class': directives.class_option,
         'caption': directives.unchanged_required,
         'glob': directives.flag,
         'hidden': directives.flag,
@@ -78,7 +79,9 @@ class TocTree(SphinxDirective):
         subnode['numbered'] = self.options.get('numbered', 0)
         subnode['titlesonly'] = 'titlesonly' in self.options
         self.set_source_info(subnode)
-        wrappernode = nodes.compound(classes=['toctree-wrapper'])
+        wrappernode = nodes.compound(
+            classes=['toctree-wrapper', *self.options.get('class', ())],
+        )
         wrappernode.append(subnode)
         self.add_name(wrappernode)
 
@@ -198,7 +201,7 @@ class Author(SphinxDirective):
         else:
             text = _('Author: ')
         emph += nodes.Text(text)
-        inodes, messages = self.state.inline_text(self.arguments[0], self.lineno)
+        inodes, messages = self.parse_inline(self.arguments[0])
         emph.extend(inodes)
 
         ret: list[Node] = [para]
@@ -247,7 +250,7 @@ class Centered(SphinxDirective):
         if not self.arguments:
             return []
         subnode: Element = addnodes.centered()
-        inodes, messages = self.state.inline_text(self.arguments[0], self.lineno)
+        inodes, messages = self.parse_inline(self.arguments[0])
         subnode.extend(inodes)
 
         ret: list[Node] = [subnode]
@@ -267,15 +270,12 @@ class Acks(SphinxDirective):
     option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
-        node = addnodes.acks()
-        node.document = self.state.document
-        self.state.nested_parse(self.content, self.content_offset, node)
-        if len(node.children) != 1 or not isinstance(node.children[0],
-                                                     nodes.bullet_list):
+        children = self.parse_content_to_nodes()
+        if len(children) != 1 or not isinstance(children[0], nodes.bullet_list):
             logger.warning(__('.. acks content is not a list'),
                            location=(self.env.docname, self.lineno))
             return []
-        return [node]
+        return [addnodes.acks('', *children)]
 
 
 class HList(SphinxDirective):
@@ -293,15 +293,12 @@ class HList(SphinxDirective):
 
     def run(self) -> list[Node]:
         ncolumns = self.options.get('columns', 2)
-        node = nodes.paragraph()
-        node.document = self.state.document
-        self.state.nested_parse(self.content, self.content_offset, node)
-        if len(node.children) != 1 or not isinstance(node.children[0],
-                                                     nodes.bullet_list):
+        children = self.parse_content_to_nodes()
+        if len(children) != 1 or not isinstance(children[0], nodes.bullet_list):
             logger.warning(__('.. hlist content is not a list'),
                            location=(self.env.docname, self.lineno))
             return []
-        fulllist = node.children[0]
+        fulllist = children[0]
         # create a hlist node where the items are distributed
         npercol, nmore = divmod(len(fulllist), ncolumns)
         index = 0

sphinx/directives/patches.py

@@ -176,12 +176,38 @@ class MathDirective(SphinxDirective):
         ret.insert(0, target)
 
 
+class Rubric(SphinxDirective):
+    """A patch of the docutils' :rst:dir:`rubric` directive,
+    which adds a level option to specify the heading level of the rubric.
+    """
+
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {
+        'class': directives.class_option,
+        'name': directives.unchanged,
+        'level': lambda c: directives.choice(c, ('1', '2', '3', '4', '5', '6')),
+    }
+
+    def run(self) -> list[Node]:
+        set_classes(self.options)
+        rubric_text = self.arguments[0]
+        textnodes, messages = self.parse_inline(rubric_text, lineno=self.lineno)
+        rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
+        self.add_name(rubric)
+        if 'level' in self.options:
+            rubric['level'] = int(self.options['level'])
+        return [rubric, *messages]
+
+
 def setup(app: Sphinx) -> ExtensionMetadata:
     directives.register_directive('figure', Figure)
     directives.register_directive('meta', Meta)
     directives.register_directive('csv-table', CSVTable)
     directives.register_directive('code', Code)
     directives.register_directive('math', MathDirective)
+    directives.register_directive('rubric', Rubric)
 
     return {
         'version': 'builtin',

sphinx/domains/__init__.py

@@ -198,7 +198,7 @@ class Domain:
     #: data value for a fresh environment
     initial_data: dict = {}
     #: data value
-    data: dict
+    data: dict[str, Any]
     #: data version, bump this when the format of `self.data` changes
     data_version = 0
 

sphinx/domains/c/__init__.py

@@ -543,7 +543,7 @@ class AliasTransform(SphinxTransform):
                 signode.clear()
                 signode += addnodes.desc_name(sig, sig)
 
-                logger.warning("Could not find C declaration for alias '%s'." % name,
+                logger.warning("Could not find C declaration for alias '%s'.", name,
                                location=node)
                 node.replace_self(signode)
                 continue
@@ -557,7 +557,7 @@ class AliasTransform(SphinxTransform):
                 signode += addnodes.desc_name(sig, sig)
 
                 logger.warning(
-                    "Can not render C declaration for alias '%s'. No such declaration." % name,
+                    "Can not render C declaration for alias '%s'. No such declaration.", name,
                     location=node)
                 node.replace_self(signode)
                 continue
@@ -835,9 +835,9 @@ class CDomain(Domain):
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_domain(CDomain)
-    app.add_config_value("c_id_attributes", [], 'env')
-    app.add_config_value("c_paren_attributes", [], 'env')
-    app.add_config_value("c_extra_keywords", _macroKeywords, 'env')
+    app.add_config_value("c_id_attributes", [], 'env', types={list, tuple})
+    app.add_config_value("c_paren_attributes", [], 'env', types={list, tuple})
+    app.add_config_value("c_extra_keywords", _macroKeywords, 'env', types={set, list})
     app.add_config_value("c_maximum_signature_line_length", None, 'env', types={int, None})
     app.add_post_transform(AliasTransform)