Sphinx 7.2.6__py3-none-any.whl → 7.3.0__py3-none-any.whl

sphinx/__init__.py

@@ -1,5 +1,8 @@
 """The Sphinx documentation toolchain."""
 
+__version__ = '7.3.0'
+__display_version__ = __version__  # used for command line version
+
 # Keep this file executable as-is in Python 3!
 # (Otherwise getting the version out of it when packaging is impossible.)
 
@@ -13,14 +16,9 @@ from .deprecation import RemovedInNextVersionWarning
 # Users can avoid this by using environment variable: PYTHONWARNINGS=
 if 'PYTHONWARNINGS' not in os.environ:
     warnings.filterwarnings('default', category=RemovedInNextVersionWarning)
-# docutils.io using mode='rU' for open
-warnings.filterwarnings('ignore', "'U' mode is deprecated",
-                        DeprecationWarning, module='docutils.io')
-warnings.filterwarnings('ignore', 'The frontend.Option class .*',
-                        DeprecationWarning, module='docutils.frontend')
-
-__version__ = '7.2.6'
-__display_version__ = __version__  # used for command line version
+warnings.filterwarnings(
+    'ignore', 'The frontend.Option class .*', DeprecationWarning, module='docutils.frontend'
+)
 
 #: Version info for better programmatic use.
 #:
@@ -30,7 +28,7 @@ __display_version__ = __version__  # used for command line version
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (7, 2, 6, 'final', 0)
+version_info = (7, 3, 0, 'final', 0)
 
 package_dir = path.abspath(path.dirname(__file__))
 
@@ -44,6 +42,7 @@ if _in_development:
             ['git', 'rev-parse', '--short', 'HEAD'],
             cwd=package_dir,
             capture_output=True,
+            check=False,
             encoding='ascii',
             errors='surrogateescape',
         ).stdout:

sphinx/addnodes.py

@@ -12,24 +12,7 @@ if TYPE_CHECKING:
     from docutils.nodes import Element
 
     from sphinx.application import Sphinx
-
-# deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
-    'meta': (nodes.meta, 'docutils.nodes.meta'),  # type: ignore[attr-defined]
-    'docutils_meta': (nodes.meta, 'docutils.nodes.meta'),  # type: ignore[attr-defined]
-}
-
-
-def __getattr__(name):
-    if name not in _DEPRECATED_OBJECTS:
-        msg = f'module {__name__!r} has no attribute {name!r}'
-        raise AttributeError(msg)
-
-    from sphinx.deprecation import _deprecation_warning
-
-    deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
-    _deprecation_warning(__name__, name, canonical_name, remove=(7, 0))
-    return deprecated_object
+    from sphinx.util.typing import ExtensionMetadata
 
 
 class document(nodes.document):
@@ -44,7 +27,7 @@ class document(nodes.document):
 
     def set_id(self, node: Element, msgnode: Element | None = None,
                suggested_prefix: str = '') -> str:
-        return super().set_id(node, msgnode, suggested_prefix)  # type: ignore[call-arg]
+        return super().set_id(node, msgnode, suggested_prefix)
 
 
 class translatable(nodes.Node):
@@ -79,6 +62,7 @@ class translatable(nodes.Node):
 
 class not_smartquotable:
     """A node which does not support smart-quotes."""
+
     support_smartquotes = False
 
 
@@ -87,7 +71,7 @@ class toctree(nodes.General, nodes.Element, translatable):
 
     def preserve_original_messages(self) -> None:
         # toctree entries
-        rawentries = self.setdefault('rawentries', [])
+        rawentries: list[str] = self.setdefault('rawentries', [])
         for title, _docname in self['entries']:
             if title:
                 rawentries.append(title)
@@ -163,11 +147,12 @@ class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Tex
 
     This node always has the classes ``sig``, ``sig-object``, and the domain it belongs to.
     """
+
     # Note: the domain name is being added through a post-transform DescSigAddDomainAsClass
     classes = ['sig', 'sig-object']
 
     @property
-    def child_text_separator(self):
+    def child_text_separator(self) -> str:  # type: ignore[override]
         if self.get('is_multiline'):
             return ' '
         else:
@@ -181,6 +166,7 @@ class desc_signature_line(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     with ``is_multiline`` set to ``True``.
     Set ``add_permalink = True`` for the line that should get the permalink.
     """
+
     sphinx_line_type = ''
 
 
@@ -199,6 +185,7 @@ class desc_inline(_desc_classes_injector, nodes.Inline, nodes.TextElement):
     This node always has the classes ``sig``, ``sig-inline``,
     and the name of the domain it belongs to.
     """
+
     classes = ['sig', 'sig-inline']
 
     def __init__(self, domain: str, *args: Any, **kwargs: Any) -> None:
@@ -219,6 +206,7 @@ class desc_name(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.FixedTex
 
     This node always has the class ``sig-name``.
     """
+
     classes = ['sig-name', 'descname']  # 'descname' is for backwards compatibility
 
 
@@ -230,6 +218,7 @@ class desc_addname(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Fixed
 
     This node always has the class ``sig-prename``.
     """
+
     # 'descclassname' is for backwards compatibility
     classes = ['sig-prename', 'descclassname']
 
@@ -256,9 +245,10 @@ class desc_parameterlist(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     Set ``multi_line_parameter_list = True`` to describe a multi-line parameter list.
     In that case each parameter will then be written on its own, indented line.
     """
+
     child_text_separator = ', '
 
-    def astext(self):
+    def astext(self) -> str:
         return f'({super().astext()})'
 
 
@@ -269,9 +259,10 @@ class desc_type_parameter_list(nodes.Part, nodes.Inline, nodes.FixedTextElement)
     Set ``multi_line_parameter_list = True`` to describe a multi-line type parameters list.
     In that case each type parameter will then be written on its own, indented line.
     """
+
     child_text_separator = ', '
 
-    def astext(self):
+    def astext(self) -> str:
         return f'[{super().astext()}]'
 
 
@@ -285,6 +276,7 @@ class desc_type_parameter(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 
 class desc_optional(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for marking optional parts of the parameter list."""
+
     child_text_separator = ', '
 
     def astext(self) -> str:
@@ -315,6 +307,7 @@ SIG_ELEMENTS: set[type[desc_sig_element]] = set()
 
 class desc_sig_element(nodes.inline, _desc_classes_injector):
     """Common parent class of nodes for inline text of a signature."""
+
     classes: list[str] = []
 
     def __init__(self, rawsource: str = '', text: str = '',
@@ -322,7 +315,7 @@ class desc_sig_element(nodes.inline, _desc_classes_injector):
         super().__init__(rawsource, text, *children, **attributes)
         self['classes'].extend(self.classes)
 
-    def __init_subclass__(cls, *, _sig_element=False, **kwargs):
+    def __init_subclass__(cls, *, _sig_element: bool = False, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
         if _sig_element:
             # add the class to the SIG_ELEMENTS set if asked
@@ -334,6 +327,7 @@ class desc_sig_element(nodes.inline, _desc_classes_injector):
 
 class desc_sig_space(desc_sig_element, _sig_element=True):
     """Node for a space in a signature."""
+
     classes = ["w"]
 
     def __init__(self, rawsource: str = '', text: str = ' ',
@@ -343,41 +337,49 @@ class desc_sig_space(desc_sig_element, _sig_element=True):
 
 class desc_sig_name(desc_sig_element, _sig_element=True):
     """Node for an identifier in a signature."""
+
     classes = ["n"]
 
 
 class desc_sig_operator(desc_sig_element, _sig_element=True):
     """Node for an operator in a signature."""
+
     classes = ["o"]
 
 
 class desc_sig_punctuation(desc_sig_element, _sig_element=True):
     """Node for punctuation in a signature."""
+
     classes = ["p"]
 
 
 class desc_sig_keyword(desc_sig_element, _sig_element=True):
     """Node for a general keyword in a signature."""
+
     classes = ["k"]
 
 
 class desc_sig_keyword_type(desc_sig_element, _sig_element=True):
     """Node for a keyword which is a built-in type in a signature."""
+
     classes = ["kt"]
 
 
 class desc_sig_literal_number(desc_sig_element, _sig_element=True):
     """Node for a numeric literal in a signature."""
+
     classes = ["m"]
 
 
 class desc_sig_literal_string(desc_sig_element, _sig_element=True):
     """Node for a string literal in a signature."""
+
     classes = ["s"]
 
 
 class desc_sig_literal_char(desc_sig_element, _sig_element=True):
     """Node for a character literal in a signature."""
+
     classes = ["sc"]
 
 
@@ -387,8 +389,8 @@ class desc_sig_literal_char(desc_sig_element, _sig_element=True):
 class versionmodified(nodes.Admonition, nodes.TextElement):
     """Node for version change entries.
 
-    Currently used for "versionadded", "versionchanged" and "deprecated"
-    directives.
+    Currently used for "versionadded", "versionchanged", "deprecated"
+    and "versionremoved" directives.
     """
 
 
@@ -425,7 +427,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
 
 
 class centered(nodes.Part, nodes.TextElement):
-    """This node is deprecated."""
+    """Deprecated."""
 
 
 class acks(nodes.Element):
@@ -479,6 +481,7 @@ class pending_xref(nodes.Inline, nodes.Element):
     These nodes are resolved before writing output, in
     BuildEnvironment.resolve_references.
     """
+
     child_text_separator = ''
 
 
@@ -553,7 +556,7 @@ class manpage(nodes.Inline, nodes.FixedTextElement):
     """Node for references to manpages."""
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_node(toctree)
 
     app.add_node(desc)

sphinx/application.py

@@ -10,10 +10,10 @@ import os
 import pickle
 import sys
 from collections import deque
-from collections.abc import Sequence  # NoQA: TCH003
+from collections.abc import Collection, Sequence  # NoQA: TCH003
 from io import StringIO
 from os import path
-from typing import IO, TYPE_CHECKING, Any, Callable
+from typing import IO, TYPE_CHECKING, Any, Callable, Literal
 
 from docutils.nodes import TextElement  # NoQA: TCH002
 from docutils.parsers.rst import Directive, roles
@@ -22,7 +22,7 @@ from pygments.lexer import Lexer  # NoQA: TCH002
 
 import sphinx
 from sphinx import locale, package_dir
-from sphinx.config import Config
+from sphinx.config import ENUM, Config, _ConfigRebuild
 from sphinx.environment import BuildEnvironment
 from sphinx.errors import ApplicationError, ConfigError, VersionRequirementError
 from sphinx.events import EventManager
@@ -33,7 +33,7 @@ from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import docutils, logging
 from sphinx.util._pathlib import _StrPath
 from sphinx.util.build_phase import BuildPhase
-from sphinx.util.console import bold  # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.display import progress_message
 from sphinx.util.i18n import CatalogRepository
 from sphinx.util.logging import prefixed_warnings
@@ -210,10 +210,6 @@ class Sphinx:
             self.confdir = _StrPath(confdir).resolve()
             self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
 
-        # initialize some limited config variables before initialize i18n and loading
-        # extensions
-        self.config.pre_init_values()
-
         # set up translation infrastructure
         self._init_i18n()
 
@@ -252,8 +248,8 @@ class Sphinx:
                            "This is needed for conf.py to behave as a Sphinx extension."),
                     )
 
-        # now that we know all config values, collect them from conf.py
-        self.config.init_values()
+        # Report any warnings for overrides.
+        self.config._report_override_warnings()
         self.events.emit('config-inited', self.config)
 
         # create the project
@@ -507,8 +503,8 @@ class Sphinx:
         self.registry.add_builder(builder, override=override)
 
     # TODO(stephenfin): Describe 'types' parameter
-    def add_config_value(self, name: str, default: Any, rebuild: bool | str,
-                         types: Any = ()) -> None:
+    def add_config_value(self, name: str, default: Any, rebuild: _ConfigRebuild,
+                         types: type | Collection[type] | ENUM = ()) -> None:
         """Register a configuration value.
 
         This is necessary for Sphinx to recognize new values and set default
@@ -542,8 +538,6 @@ class Sphinx:
            converted internally.
         """
         logger.debug('[app] adding config value: %r', (name, default, rebuild, types))
-        if rebuild in (False, True):
-            rebuild = 'env' if rebuild else ''
         self.config.add(name, default, rebuild, types)
 
     def add_event(self, name: str) -> None:
@@ -1313,7 +1307,7 @@ class Sphinx:
 
         return True
 
-    def set_html_assets_policy(self, policy):
+    def set_html_assets_policy(self, policy: Literal['always', 'per_page']) -> None:
         """Set the policy to include assets in HTML pages.
 
         - always: include the assets in all the pages

sphinx/builders/__init__.py

@@ -17,7 +17,7 @@ from sphinx.errors import SphinxError
 from sphinx.locale import __
 from sphinx.util import UnicodeDecodeErrorHandler, get_filetype, import_object, logging, rst
 from sphinx.util.build_phase import BuildPhase
-from sphinx.util.console import bold  # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import sphinx_domains
 from sphinx.util.i18n import CatalogInfo, CatalogRepository, docname_to_domain
@@ -25,8 +25,8 @@ from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath
 from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, parallel_available
 
 # side effect: registers roles and directives
-from sphinx import directives  # noqa: F401  isort:skip
-from sphinx import roles  # noqa: F401  isort:skip
+from sphinx import directives  # NoQA: F401  isort:skip
+from sphinx import roles  # NoQA: F401  isort:skip
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
@@ -314,8 +314,7 @@ class Builder:
 
         doccount = len(updated_docnames)
         logger.info(bold(__('looking for now-outdated files... ')), nonl=True)
-        for docname in self.env.check_dependents(self.app, updated_docnames):
-            updated_docnames.add(docname)
+        updated_docnames.update(self.env.check_dependents(self.app, updated_docnames))
         outdated = len(updated_docnames) - doccount
         if outdated:
             logger.info(__('%d found'), outdated)
@@ -520,7 +519,7 @@ class Builder:
         doctree.settings = doctree.settings.copy()
         doctree.settings.warning_stream = None
         doctree.settings.env = None
-        doctree.settings.record_dependencies = None  # type: ignore[assignment]
+        doctree.settings.record_dependencies = None
 
         doctree_filename = path.join(self.doctreedir, docname + '.doctree')
         ensuredir(path.dirname(doctree_filename))

sphinx/builders/_epub_base.py

@@ -168,7 +168,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         self.refnodes: list[dict[str, Any]] = []
 
     def create_build_info(self) -> BuildInfo:
-        return BuildInfo(self.config, self.tags, ['html', 'epub'])
+        return BuildInfo(self.config, self.tags, frozenset({'html', 'epub'}))
 
     def get_theme_config(self) -> tuple[str, dict]:
         return self.config.epub_theme, self.config.epub_theme_options
@@ -317,7 +317,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
         def footnote_spot(tree: nodes.document) -> tuple[Element, int]:
             """Find or create a spot to place footnotes.
 
-            The function returns the tuple (parent, index)."""
+            The function returns the tuple (parent, index).
+            """
             # The code uses the following heuristic:
             # a) place them after the last existing footnote
             # b) place them after an (empty) Footnotes rubric
@@ -417,7 +418,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
                                    path.join(self.srcdir, src), err)
                 continue
             if self.config.epub_fix_images:
-                if img.mode in ('P',):
+                if img.mode == 'P':
                     # See the Pillow documentation for Image.convert()
                     # https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.convert
                     img = img.convert()
@@ -480,7 +481,6 @@ class EpubBuilder(StandaloneHTMLBuilder):
         """Create a dictionary with all metadata for the content.opf
         file properly escaped.
         """
-
         if (source_date_epoch := os.getenv('SOURCE_DATE_EPOCH')) is not None:
             time_tuple = time.gmtime(int(source_date_epoch))
         else:
@@ -510,11 +510,19 @@ class EpubBuilder(StandaloneHTMLBuilder):
 
         # files
         self.files: list[str] = []
-        self.ignored_files = ['.buildinfo', 'mimetype', 'content.opf',
-                              'toc.ncx', 'META-INF/container.xml',
-                              'Thumbs.db', 'ehthumbs.db', '.DS_Store',
-                              'nav.xhtml', self.config.epub_basename + '.epub'] + \
-            self.config.epub_exclude_files
+        self.ignored_files = [
+            '.buildinfo',
+            'mimetype',
+            'content.opf',
+            'toc.ncx',
+            'META-INF/container.xml',
+            'Thumbs.db',
+            'ehthumbs.db',
+            '.DS_Store',
+            'nav.xhtml',
+            self.config.epub_basename + '.epub',
+            *self.config.epub_exclude_files,
+        ]
         if not self.use_index:
             self.ignored_files.append('genindex' + self.out_suffix)
         for root, dirs, files in os.walk(self.outdir):

sphinx/builders/changes.py

@@ -12,20 +12,22 @@ from sphinx.domains.changeset import ChangeSetDomain
 from sphinx.locale import _, __
 from sphinx.theming import HTMLThemeFactory
 from sphinx.util import logging
-from sphinx.util.console import bold  # type: ignore[attr-defined]
+from sphinx.util.console import bold
 from sphinx.util.fileutil import copy_asset_file
 from sphinx.util.osutil import ensuredir, os_path
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
 
 class ChangesBuilder(Builder):
     """
-    Write a summary with all versionadded/changed directives.
+    Write a summary with all versionadded/changed/deprecated/removed directives.
     """
+
     name = 'changes'
     epilog = __('The overview file is in %(outdir)s.')
 
@@ -42,6 +44,7 @@ class ChangesBuilder(Builder):
         'versionadded': 'added',
         'versionchanged': 'changed',
         'deprecated': 'deprecated',
+        'versionremoved': 'removed',
     }
 
     def write(self, *ignored: Any) -> None:
@@ -105,7 +108,9 @@ class ChangesBuilder(Builder):
 
         hltext = ['.. versionadded:: %s' % version,
                   '.. versionchanged:: %s' % version,
-                  '.. deprecated:: %s' % version]
+                  '.. deprecated:: %s' % version,
+                  '.. versionremoved:: %s' % version,
+                  ]
 
         def hl(no: int, line: str) -> str:
             line = '<a name="L%s"> </a>' % no + html.escape(line)
@@ -142,7 +147,7 @@ class ChangesBuilder(Builder):
 
     def hl(self, text: str, version: str) -> str:
         text = html.escape(text)
-        for directive in ('versionchanged', 'versionadded', 'deprecated'):
+        for directive in ('versionchanged', 'versionadded', 'deprecated', 'versionremoved'):
             text = text.replace(f'.. {directive}:: {version}',
                                 f'<b>.. {directive}:: {version}</b>')
         return text
@@ -151,7 +156,7 @@ class ChangesBuilder(Builder):
         pass
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(ChangesBuilder)
 
     return {

sphinx/builders/dirhtml.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from os import path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.util import logging
@@ -11,6 +11,7 @@ from sphinx.util.osutil import SEP, os_path
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -21,6 +22,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
     a directory given by their pagename, so that generated URLs don't have
     ``.html`` in them.
     """
+
     name = 'dirhtml'
 
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
@@ -41,7 +43,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
         return outfilename
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.setup_extension('sphinx.builders.html')
 
     app.add_builder(DirectoryHTMLBuilder)

sphinx/builders/dummy.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from sphinx.builders import Builder
 from sphinx.locale import __
@@ -11,6 +11,7 @@ if TYPE_CHECKING:
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 
 class DummyBuilder(Builder):
@@ -38,7 +39,7 @@ class DummyBuilder(Builder):
         pass
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(DummyBuilder)
 
     return {

sphinx/builders/epub3.py

@@ -22,6 +22,7 @@ from sphinx.util.osutil import make_filename
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -75,6 +76,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
     and META-INF/container.xml. Afterwards, all necessary files are zipped to
     an epub file.
     """
+
     name = 'epub'
     epilog = __('The ePub file is in %(outdir)s.')
 
@@ -240,7 +242,7 @@ def validate_config_values(app: Sphinx) -> None:
 
 
 def convert_epub_css_files(app: Sphinx, config: Config) -> None:
-    """This converts string styled epub_css_files to tuple styled one."""
+    """Convert string styled epub_css_files to tuple styled one."""
     epub_css_files: list[tuple[str, dict[str, Any]]] = []
     for entry in config.epub_css_files:
         if isinstance(entry, str):
@@ -256,11 +258,11 @@ def convert_epub_css_files(app: Sphinx, config: Config) -> None:
     config.epub_css_files = epub_css_files  # type: ignore[attr-defined]
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(Epub3Builder)
 
     # config values
-    app.add_config_value('epub_basename', lambda self: make_filename(self.project), False)
+    app.add_config_value('epub_basename', lambda self: make_filename(self.project), '')
     app.add_config_value('epub_version', 3.0, 'epub')  # experimental
     app.add_config_value('epub_theme', 'epub', 'epub')
     app.add_config_value('epub_theme_options', {}, 'epub')