Sphinx 8.0.1__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/directives/other.py

@@ -78,17 +78,19 @@ class TocTree(SphinxDirective):
         subnode['numbered'] = self.options.get('numbered', 0)
         subnode['titlesonly'] = 'titlesonly' in self.options
         self.set_source_info(subnode)
+        self.parse_content(subnode)
+
         wrappernode = nodes.compound(
             classes=['toctree-wrapper', *self.options.get('class', ())],
         )
         wrappernode.append(subnode)
         self.add_name(wrappernode)
+        return [wrappernode]
 
-        ret = self.parse_content(subnode)
-        ret.append(wrappernode)
-        return ret
-
-    def parse_content(self, toctree: addnodes.toctree) -> list[Node]:
+    def parse_content(self, toctree: addnodes.toctree) -> None:
+        """
+        Populate ``toctree['entries']`` and ``toctree['includefiles']`` from content.
+        """
         generated_docnames = frozenset(StandardDomain._virtual_doc_names)
         suffixes = self.config.source_suffix
         current_docname = self.env.docname
@@ -99,7 +101,6 @@ class TocTree(SphinxDirective):
         all_docnames.remove(current_docname)  # remove current document
         frozen_all_docnames = frozenset(all_docnames)
 
-        ret: list[Node] = []
         excluded = Matcher(self.config.exclude_patterns)
         for entry in self.content:
             if not entry:
@@ -110,17 +111,23 @@ class TocTree(SphinxDirective):
             url_match = url_re.match(entry) is not None
             if glob and glob_re.match(entry) and not explicit and not url_match:
                 pat_name = docname_join(current_docname, entry)
-                doc_names = sorted(patfilter(all_docnames, pat_name))
+                doc_names = sorted(
+                    docname
+                    for docname in patfilter(all_docnames, pat_name)
+                    # don't include generated documents in globs
+                    if docname not in generated_docnames
+                )
+                if not doc_names:
+                    logger.warning(
+                        __("toctree glob pattern %r didn't match any documents"),
+                        entry,
+                        location=toctree,
+                    )
+
                 for docname in doc_names:
-                    if docname in generated_docnames:
-                        # don't include generated documents in globs
-                        continue
                     all_docnames.remove(docname)  # don't include it again
                     toctree['entries'].append((None, docname))
                     toctree['includefiles'].append(docname)
-                if not doc_names:
-                    logger.warning(__("toctree glob pattern %r didn't match any documents"),
-                                   entry, location=toctree)
                 continue
 
             if explicit:
@@ -145,22 +152,26 @@ class TocTree(SphinxDirective):
 
             if docname not in frozen_all_docnames:
                 if excluded(str(self.env.doc2path(docname, False))):
-                    message = __('toctree contains reference to excluded document %r')
+                    msg = __('toctree contains reference to excluded document %r')
                     subtype = 'excluded'
                 else:
-                    message = __('toctree contains reference to nonexisting document %r')
+                    msg = __('toctree contains reference to nonexisting document %r')
                     subtype = 'not_readable'
 
-                logger.warning(message, docname, type='toc', subtype=subtype,
-                               location=toctree)
+                logger.warning(
+                    msg, docname, type='toc', subtype=subtype, location=toctree
+                )
                 self.env.note_reread()
                 continue
 
             if docname in all_docnames:
                 all_docnames.remove(docname)
             else:
-                logger.warning(__('duplicated entry found in toctree: %s'), docname,
-                               location=toctree)
+                logger.warning(
+                    __('duplicated entry found in toctree: %s'),
+                    docname,
+                    location=toctree,
+                )
 
             toctree['entries'].append((title, docname))
             toctree['includefiles'].append(docname)
@@ -170,8 +181,6 @@ class TocTree(SphinxDirective):
             toctree['entries'] = list(reversed(toctree['entries']))
             toctree['includefiles'] = list(reversed(toctree['includefiles']))
 
-        return ret
-
 
 class Author(SphinxDirective):
     """
@@ -208,7 +217,7 @@ class Author(SphinxDirective):
         return ret
 
 
-class SeeAlso(BaseAdmonition):  # type: ignore[misc]
+class SeeAlso(BaseAdmonition):
     """
     An admonition mentioning things to look at as reference.
     """
@@ -271,8 +280,10 @@ class Acks(SphinxDirective):
     def run(self) -> list[Node]:
         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))
+            logger.warning(
+                __('.. acks content is not a list'),
+                location=(self.env.docname, self.lineno),
+            )
             return []
         return [addnodes.acks('', *children)]
 
@@ -294,8 +305,10 @@ class HList(SphinxDirective):
         ncolumns = self.options.get('columns', 2)
         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))
+            logger.warning(
+                __('.. hlist content is not a list'),
+                location=(self.env.docname, self.lineno),
+            )
             return []
         fulllist = children[0]
         # create a hlist node where the items are distributed
@@ -337,13 +350,16 @@ class Only(SphinxDirective):
         memo.title_styles = []
         memo.section_level = 0
         try:
-            self.state.nested_parse(self.content, self.content_offset,
-                                    node, match_titles=True)
+            self.state.nested_parse(
+                self.content, self.content_offset, node, match_titles=True
+            )
             title_styles = memo.title_styles
-            if (not surrounding_title_styles or
-                    not title_styles or
-                    title_styles[0] not in surrounding_title_styles or
-                    not self.state.parent):
+            if (
+                not surrounding_title_styles
+                or not title_styles
+                or title_styles[0] not in surrounding_title_styles
+                or not self.state.parent
+            ):
                 # No nested sections so no special handling needed.
                 return [node]
             # Calculate the depths of the current and nested sections.
@@ -378,7 +394,6 @@ class Include(BaseInclude, SphinxDirective):
     """
 
     def run(self) -> Sequence[Node]:
-
         # To properly emit "include-read" events from included RST text,
         # we must patch the ``StateMachine.insert_input()`` method.
         # In the future, docutils will hopefully offer a way for Sphinx
@@ -390,7 +405,7 @@ class Include(BaseInclude, SphinxDirective):
             # In docutils 0.18 and later, there are two lines at the end
             # that act as markers.
             # We must preserve them and leave them out of the include-read event:
-            text = "\n".join(include_lines[:-2])
+            text = '\n'.join(include_lines[:-2])
 
             path = Path(relpath(abspath(source), start=self.env.srcdir))
             docname = self.env.docname
@@ -413,8 +428,7 @@ class Include(BaseInclude, SphinxDirective):
             # See https://github.com/python/mypy/issues/2427 for details on the mypy issue
             self.state_machine.insert_input = _insert_input
 
-        if self.arguments[0].startswith('<') and \
-           self.arguments[0].endswith('>'):
+        if self.arguments[0].startswith('<') and self.arguments[0].endswith('>'):
             # docutils "standard" includes, do not do path processing
             return super().run()
         rel_filename, filename = self.env.relfn2path(self.arguments[0])

sphinx/directives/patches.py

@@ -12,7 +12,6 @@ from docutils.parsers.rst.directives.misc import Meta
 from docutils.parsers.rst.roles import set_classes
 
 from sphinx.directives import optional_int
-from sphinx.domains.math import MathDomain
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
@@ -63,10 +62,14 @@ class CSVTable(tables.CSVTable):  # type: ignore[misc]
             env = self.state.document.settings.env
             filename = self.options['file']
             if path.exists(filename):
-                logger.warning(__('":file:" option for csv-table directive now recognizes '
-                                  'an absolute path as a relative path from source directory. '
-                                  'Please update your document.'),
-                               location=(env.docname, self.lineno))
+                logger.warning(
+                    __(
+                        '":file:" option for csv-table directive now recognizes '
+                        'an absolute path as a relative path from source directory. '
+                        'Please update your document.'
+                    ),
+                    location=(env.docname, self.lineno),
+                )
             else:
                 abspath = path.join(env.srcdir, os_path(self.options['file'][1:]))
                 docdir = path.dirname(env.doc2path(env.docname))
@@ -95,10 +98,13 @@ class Code(SphinxDirective):
 
         set_classes(self.options)
         code = '\n'.join(self.content)
-        node = nodes.literal_block(code, code,
-                                   classes=self.options.get('classes', []),
-                                   force='force' in self.options,
-                                   highlight_args={})
+        node = nodes.literal_block(
+            code,
+            code,
+            classes=self.options.get('classes', []),
+            force='force' in self.options,
+            highlight_args={},
+        )
         self.add_name(node)
         set_source_info(self, node)
 
@@ -109,8 +115,9 @@ class Code(SphinxDirective):
             # no highlight language specified.  Then this directive refers the current
             # highlight setting via ``highlight`` directive or ``highlight_language``
             # configuration.
-            node['language'] = self.env.temp_data.get('highlight_language',
-                                                      self.config.highlight_language)
+            node['language'] = self.env.temp_data.get(
+                'highlight_language', self.config.highlight_language
+            )
 
         if 'number-lines' in self.options:
             node['linenos'] = True
@@ -139,12 +146,15 @@ class MathDirective(SphinxDirective):
         if self.arguments and self.arguments[0]:
             latex = self.arguments[0] + '\n\n' + latex
         label = self.options.get('label', self.options.get('name'))
-        node = nodes.math_block(latex, latex,
-                                classes=self.options.get('class', []),
-                                docname=self.env.docname,
-                                number=None,
-                                label=label,
-                                nowrap='nowrap' in self.options)
+        node = nodes.math_block(
+            latex,
+            latex,
+            classes=self.options.get('class', []),
+            docname=self.env.docname,
+            number=None,
+            label=label,
+            nowrap='nowrap' in self.options,
+        )
         self.add_name(node)
         self.set_source_info(node)
 
@@ -158,14 +168,14 @@ class MathDirective(SphinxDirective):
         # assign label automatically if math_number_all enabled
         if node['label'] == '' or (self.config.math_number_all and not node['label']):
             seq = self.env.new_serialno('sphinx.ext.math#equations')
-            node['label'] = "%s:%d" % (self.env.docname, seq)
+            node['label'] = f'{self.env.docname}:{seq}'
 
         # no targets and numbers are needed
         if not node['label']:
             return
 
         # register label to domain
-        domain = cast(MathDomain, self.env.get_domain('math'))
+        domain = self.env.domains.math_domain
         domain.note_equation(self.env.docname, node['label'], location=node)
         node['number'] = domain.get_equation_number_for(node['label'])
 

sphinx/domains/__init__.py

@@ -7,20 +7,17 @@ and roles describing e.g. constructs of one programming language.
 from __future__ import annotations
 
 import copy
-from abc import ABC, abstractmethod
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, NamedTuple, cast
+from typing import TYPE_CHECKING
 
-from docutils.nodes import Element, Node, system_message
-
-from sphinx.errors import SphinxError
+from sphinx.domains._index import Index, IndexEntry
 from sphinx.locale import _
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable, Sequence
-    from typing import TypeAlias
+    from collections.abc import Callable, Iterable, Sequence, Set
+    from typing import Any
 
     from docutils import nodes
+    from docutils.nodes import Element, Node
     from docutils.parsers.rst import Directive
     from docutils.parsers.rst.states import Inliner
 
@@ -28,7 +25,14 @@ if TYPE_CHECKING:
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
     from sphinx.roles import XRefRole
-    from sphinx.util.typing import RoleFunction
+    from sphinx.util.typing import RoleFunction, TitleGetter
+
+__all__ = (
+    'Domain',
+    'Index',
+    'IndexEntry',
+    'ObjType',
+)
 
 
 class ObjType:
@@ -50,112 +54,10 @@ class ObjType:
         'searchprio': 1,
     }
 
-    def __init__(self, lname: str, *roles: Any, **attrs: Any) -> None:
-        self.lname = lname
-        self.roles: tuple = roles
-        self.attrs: dict = self.known_attrs.copy()
-        self.attrs.update(attrs)
-
-
-class IndexEntry(NamedTuple):
-    name: str
-    subtype: int
-    docname: str
-    anchor: str
-    extra: str
-    qualifier: str
-    descr: str
-
-
-class Index(ABC):
-    """
-    An Index is the description for a domain-specific index.  To add an index to
-    a domain, subclass Index, overriding the three name attributes:
-
-    * `name` is an identifier used for generating file names.
-      It is also used for a hyperlink target for the index. Therefore, users can
-      refer the index page using ``ref`` role and a string which is combined
-      domain name and ``name`` attribute (ex. ``:ref:`py-modindex```).
-    * `localname` is the section title for the index.
-    * `shortname` is a short name for the index, for use in the relation bar in
-      HTML output.  Can be empty to disable entries in the relation bar.
-
-    and providing a :meth:`generate()` method.  Then, add the index class to
-    your domain's `indices` list.  Extensions can add indices to existing
-    domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain()`.
-
-    .. versionchanged:: 3.0
-
-       Index pages can be referred by domain name and index name via
-       :rst:role:`ref` role.
-    """
-
-    name: str
-    localname: str
-    shortname: str | None = None
-
-    def __init__(self, domain: Domain) -> None:
-        if not self.name or self.localname is None:
-            raise SphinxError('Index subclass %s has no valid name or localname'
-                              % self.__class__.__name__)
-        self.domain = domain
-
-    @abstractmethod
-    def generate(self, docnames: Iterable[str] | None = None,
-                 ) -> tuple[list[tuple[str, list[IndexEntry]]], bool]:
-        """Get entries for the index.
-
-        If ``docnames`` is given, restrict to entries referring to these
-        docnames.
-
-        The return value is a tuple of ``(content, collapse)``:
-
-        ``collapse``
-          A boolean that determines if sub-entries should start collapsed (for
-          output formats that support collapsing sub-entries).
-
-        ``content``:
-          A sequence of ``(letter, entries)`` tuples, where ``letter`` is the
-          "heading" for the given ``entries``, usually the starting letter, and
-          ``entries`` is a sequence of single entries. Each entry is a sequence
-          ``[name, subtype, docname, anchor, extra, qualifier, descr]``. The
-          items in this sequence have the following meaning:
-
-          ``name``
-            The name of the index entry to be displayed.
-
-          ``subtype``
-            The sub-entry related type. One of:
-
-            ``0``
-              A normal entry.
-            ``1``
-              An entry with sub-entries.
-            ``2``
-              A sub-entry.
-
-          ``docname``
-            *docname* where the entry is located.
-
-          ``anchor``
-            Anchor for the entry within ``docname``
-
-          ``extra``
-            Extra info for the entry.
-
-          ``qualifier``
-            Qualifier for the description.
-
-          ``descr``
-            Description for the entry.
-
-        Qualifier and description are not rendered for some output formats such
-        as LaTeX.
-        """
-        raise NotImplementedError
-
-
-TitleGetter: TypeAlias = Callable[[Node], str | None]
+    def __init__(self, lname: str, /, *roles: Any, **attrs: Any) -> None:
+        self.lname: str = lname
+        self.roles: tuple[Any, ...] = roles
+        self.attrs: dict[str, Any] = self.known_attrs | attrs
 
 
 class Domain:
@@ -235,10 +137,8 @@ class Domain:
 
     def setup(self) -> None:
         """Set up domain object."""
-        from sphinx.domains.std import StandardDomain
-
         # Add special hyperlink target for index pages (ex. py-modindex)
-        std = cast(StandardDomain, self.env.get_domain('std'))
+        std = self.env.domains.standard_domain
         for index in self.indices:
             if index.name and index.localname:
                 docname = f"{self.name}-{index.name}"
@@ -268,7 +168,7 @@ class Domain:
         def role_adapter(typ: str, rawtext: str, text: str, lineno: int,
                          inliner: Inliner, options: dict | None = None,
                          content: Sequence[str] = (),
-                         ) -> tuple[list[Node], list[system_message]]:
+                         ) -> tuple[list[Node], list[nodes.system_message]]:
             return self.roles[name](fullname, rawtext, text, lineno,
                                     inliner, options or {}, content)
         self._role_cache[name] = role_adapter
@@ -298,7 +198,7 @@ class Domain:
         """Remove traces of a document in the domain-specific inventories."""
         pass
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
+    def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         """Merge in data regarding *docnames* from a different domaindata
         inventory (coming from a subprocess in parallel builds).
         """