Sphinx 7.1.1__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/__init__.py

@@ -19,7 +19,7 @@ warnings.filterwarnings('ignore', "'U' mode is deprecated",
 warnings.filterwarnings('ignore', 'The frontend.Option class .*',
                         DeprecationWarning, module='docutils.frontend')
 
-__version__ = '7.1.1'
+__version__ = '7.2.0'
 __display_version__ = __version__  # used for command line version
 
 #: Version info for better programmatic use.
@@ -30,7 +30,7 @@ __display_version__ = __version__  # used for command line version
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (7, 1, 1, 'final', 0)
+version_info = (7, 2, 0, 'final', 0)
 
 package_dir = path.abspath(path.dirname(__file__))
 
@@ -40,13 +40,13 @@ if _in_development:
     import subprocess
 
     try:
-        ret = subprocess.run(
-            ['git', 'show', '-s', '--pretty=format:%h'],
+        if ret := subprocess.run(
+            ['git', 'rev-parse', '--short', 'HEAD'],
             cwd=package_dir,
             capture_output=True,
             encoding='ascii',
-        ).stdout
-        if ret:
+            errors='surrogateescape',
+        ).stdout:
             __display_version__ += '+/' + ret.strip()
         del ret
     finally:

sphinx/__main__.py

@@ -1,5 +1,7 @@
 """The Sphinx documentation toolchain."""
 
+import sys
+
 from sphinx.cmd.build import main
 
-raise SystemExit(main())
+raise SystemExit(main(sys.argv[1:]))

sphinx/addnodes.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Sequence
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
-from docutils.nodes import Element
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from docutils.nodes import Element
+
     from sphinx.application import Sphinx
 
 # deprecated name -> (object to return, canonical path or empty string)
@@ -19,7 +22,8 @@ _DEPRECATED_OBJECTS = {
 
 def __getattr__(name):
     if name not in _DEPRECATED_OBJECTS:
-        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+        msg = f'module {__name__!r} has no attribute {name!r}'
+        raise AttributeError(msg)
 
     from sphinx.deprecation import _deprecation_warning
 
@@ -40,7 +44,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
+        return super().set_id(node, msgnode, suggested_prefix)  # type: ignore[call-arg]
 
 
 class translatable(nodes.Node):
@@ -294,9 +298,20 @@ class desc_annotation(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 # Leaf nodes for markup of text fragments
 #########################################
 
+#: A set of classes inheriting :class:`desc_sig_element`. Each node class
+#: is expected to be handled by the builder's translator class if the latter
+#: does not inherit from SphinxTranslator.
+#:
+#: This set can be extended manually by third-party extensions or
+#: by subclassing :class:`desc_sig_element` and using the class
+#: keyword argument `_sig_element=True`.
+SIG_ELEMENTS: set[type[desc_sig_element]] = set()
+
+
 # Signature text elements, generally translated to node.inline
 # in SigElementFallbackTransform.
-# When adding a new one, add it to SIG_ELEMENTS.
+# When adding a new one, add it to SIG_ELEMENTS via the class
+# keyword argument `_sig_element=True` (e.g., see `desc_sig_space`).
 
 class desc_sig_element(nodes.inline, _desc_classes_injector):
     """Common parent class of nodes for inline text of a signature."""
@@ -307,11 +322,17 @@ 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):
+        super().__init_subclass__(**kwargs)
+        if _sig_element:
+            # add the class to the SIG_ELEMENTS set if asked
+            SIG_ELEMENTS.add(cls)
+
 
 # to not reinvent the wheel, the classes in the following desc_sig classes
 # are based on those used in Pygments
 
-class desc_sig_space(desc_sig_element):
+class desc_sig_space(desc_sig_element, _sig_element=True):
     """Node for a space in a signature."""
     classes = ["w"]
 
@@ -320,54 +341,46 @@ class desc_sig_space(desc_sig_element):
         super().__init__(rawsource, text, *children, **attributes)
 
 
-class desc_sig_name(desc_sig_element):
+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):
+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):
+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):
+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):
+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):
+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):
+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):
+class desc_sig_literal_char(desc_sig_element, _sig_element=True):
     """Node for a character literal in a signature."""
     classes = ["sc"]
 
 
-SIG_ELEMENTS = [desc_sig_space,
-                desc_sig_name,
-                desc_sig_operator,
-                desc_sig_punctuation,
-                desc_sig_keyword, desc_sig_keyword_type,
-                desc_sig_literal_number, desc_sig_literal_string, desc_sig_literal_char]
-
-
 ###############################################################
 # new admonition-like constructs
 

sphinx/application.py

@@ -9,46 +9,48 @@ import os
 import pickle
 import sys
 from collections import deque
+from collections.abc import Sequence  # NoQA: TCH003
 from io import StringIO
 from os import path
+from pathlib import Path
 from typing import IO, TYPE_CHECKING, Any, Callable
 
-from docutils import nodes
-from docutils.nodes import Element, TextElement
-from docutils.parsers import Parser
+from docutils.nodes import TextElement  # NoQA: TCH002
 from docutils.parsers.rst import Directive, roles
-from docutils.transforms import Transform
-from pygments.lexer import Lexer
+from docutils.transforms import Transform  # NoQA: TCH002
+from pygments.lexer import Lexer  # NoQA: TCH002
 
 import sphinx
 from sphinx import locale, package_dir
 from sphinx.config import Config
-from sphinx.domains import Domain, Index
 from sphinx.environment import BuildEnvironment
-from sphinx.environment.collectors import EnvironmentCollector
 from sphinx.errors import ApplicationError, ConfigError, VersionRequirementError
 from sphinx.events import EventManager
-from sphinx.extension import Extension
 from sphinx.highlighting import lexer_classes
 from sphinx.locale import __
 from sphinx.project import Project
 from sphinx.registry import SphinxComponentRegistry
-from sphinx.roles import XRefRole
-from sphinx.theming import Theme
 from sphinx.util import docutils, logging
 from sphinx.util.build_phase import BuildPhase
-from sphinx.util.console import bold  # type: ignore
+from sphinx.util.console import bold  # type: ignore[attr-defined]
 from sphinx.util.display import progress_message
 from sphinx.util.i18n import CatalogRepository
 from sphinx.util.logging import prefixed_warnings
-from sphinx.util.osutil import abspath, ensuredir, relpath
+from sphinx.util.osutil import ensuredir, relpath
 from sphinx.util.tags import Tags
-from sphinx.util.typing import RoleFunction, TitleGetter
 
 if TYPE_CHECKING:
-    from docutils.nodes import Node  # noqa: F401
+    from docutils import nodes
+    from docutils.nodes import Element
+    from docutils.parsers import Parser
 
     from sphinx.builders import Builder
+    from sphinx.domains import Domain, Index
+    from sphinx.environment.collectors import EnvironmentCollector
+    from sphinx.extension import Extension
+    from sphinx.roles import XRefRole
+    from sphinx.theming import Theme
+    from sphinx.util.typing import RoleFunction, TitleGetter
 
 
 builtin_extensions: tuple[str, ...] = (
@@ -132,7 +134,8 @@ class Sphinx:
     warningiserror: bool
     _warncount: int
 
-    def __init__(self, srcdir: str, confdir: str | None, outdir: str, doctreedir: str,
+    def __init__(self, srcdir: str | os.PathLike[str], confdir: str | os.PathLike[str] | None,
+                 outdir: str | os.PathLike[str], doctreedir: str | os.PathLike[str],
                  buildername: str, confoverrides: dict | None = None,
                  status: IO | None = sys.stdout, warning: IO | None = sys.stderr,
                  freshenv: bool = False, warningiserror: bool = False,
@@ -145,9 +148,9 @@ class Sphinx:
         self.registry = SphinxComponentRegistry()
 
         # validate provided directories
-        self.srcdir = abspath(srcdir)
-        self.outdir = abspath(outdir)
-        self.doctreedir = abspath(doctreedir)
+        self.srcdir = Path(srcdir).resolve()
+        self.outdir = Path(outdir).resolve()
+        self.doctreedir = Path(doctreedir).resolve()
 
         if not path.isdir(self.srcdir):
             raise ApplicationError(__('Cannot find source directory (%s)') %
@@ -203,7 +206,7 @@ class Sphinx:
             self.confdir = self.srcdir
             self.config = Config({}, confoverrides or {})
         else:
-            self.confdir = abspath(confdir)
+            self.confdir = Path(confdir).resolve()
             self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
 
         # initialize some limited config variables before initialize i18n and loading
@@ -307,13 +310,13 @@ class Sphinx:
         self._fresh_env_used = True
         return env
 
+    @progress_message(__('loading pickled environment'))
     def _load_existing_env(self, filename: str) -> BuildEnvironment:
         try:
-            with progress_message(__('loading pickled environment')):
-                with open(filename, 'rb') as f:
-                    env = pickle.load(f)
-                    env.setup(self)
-                    self._fresh_env_used = False
+            with open(filename, 'rb') as f:
+                env = pickle.load(f)
+                env.setup(self)
+                self._fresh_env_used = False
         except Exception as err:
             logger.info(__('failed: %s'), err)
             env = self._create_fresh_env()
@@ -420,7 +423,8 @@ class Sphinx:
         else:
             major, minor = map(int, version.split('.')[:2])
         if (major, minor) > sphinx.version_info[:2]:
-            raise VersionRequirementError(f'{major}.{minor}')
+            req = f'{major}.{minor}'
+            raise VersionRequirementError(req)
 
     # event interface
     def connect(self, event: str, callback: Callable, priority: int = 500) -> int:
@@ -734,7 +738,7 @@ class Sphinx:
             logger.warning(__('role %r is already registered, it will be overridden'),
                            name, type='app', subtype='add_generic_role')
         role = roles.GenericRole(name, nodeclass)
-        docutils.register_role(name, role)
+        docutils.register_role(name, role)  # type: ignore[arg-type]
 
     def add_domain(self, domain: type[Domain], override: bool = False) -> None:
         """Register a domain.
@@ -811,7 +815,8 @@ class Sphinx:
     def add_object_type(self, directivename: str, rolename: str, indextemplate: str = '',
                         parse_node: Callable | None = None,
                         ref_nodeclass: type[TextElement] | None = None,
-                        objname: str = '', doc_field_types: list = [], override: bool = False,
+                        objname: str = '', doc_field_types: Sequence = (),
+                        override: bool = False,
                         ) -> None:
         """Register a new object type.
 
@@ -1028,9 +1033,6 @@ class Sphinx:
             kwargs['defer'] = 'defer'
 
         self.registry.add_js_file(filename, priority=priority, **kwargs)
-        if hasattr(self, 'builder') and hasattr(self.builder, 'add_js_file'):
-            self.builder.add_js_file(filename,
-                                     priority=priority, **kwargs)
 
     def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None:
         """Register a stylesheet to include in the HTML output.
@@ -1091,9 +1093,6 @@ class Sphinx:
         """
         logger.debug('[app] adding stylesheet: %r', filename)
         self.registry.add_css_files(filename, priority=priority, **kwargs)
-        if hasattr(self, 'builder') and hasattr(self.builder, 'add_css_file'):
-            self.builder.add_css_file(filename,
-                                      priority=priority, **kwargs)
 
     def add_latex_package(self, packagename: str, options: str | None = None,
                           after_hyperref: bool = False) -> None:
@@ -1240,8 +1239,8 @@ class Sphinx:
     def add_html_math_renderer(
         self,
         name: str,
-        inline_renderers: tuple[Callable | None, Callable | None] | None = None,
-        block_renderers: tuple[Callable | None, Callable | None] | None = None,
+        inline_renderers: tuple[Callable, Callable | None] | None = None,
+        block_renderers: tuple[Callable, Callable | None] | None = None,
     ) -> None:
         """Register a math renderer for HTML.
 
@@ -1338,7 +1337,8 @@ class TemplateBridge:
         *theme* is a :class:`sphinx.theming.Theme` object or None; in the latter
         case, *dirs* can be list of fixed directories to look for templates.
         """
-        raise NotImplementedError('must be implemented in subclasses')
+        msg = 'must be implemented in subclasses'
+        raise NotImplementedError(msg)
 
     def newest_template_mtime(self) -> float:
         """Called by the builder to determine if output files are outdated
@@ -1351,10 +1351,12 @@ class TemplateBridge:
         """Called by the builder to render a template given as a filename with
         a specified context (a Python dictionary).
         """
-        raise NotImplementedError('must be implemented in subclasses')
+        msg = 'must be implemented in subclasses'
+        raise NotImplementedError(msg)
 
     def render_string(self, template: str, context: dict) -> str:
         """Called by the builder to render a template given as a string with a
         specified context (a Python dictionary).
         """
-        raise NotImplementedError('must be implemented in subclasses')
+        msg = 'must be implemented in subclasses'
+        raise NotImplementedError(msg)

sphinx/builders/__init__.py

@@ -6,35 +6,38 @@ import codecs
 import pickle
 import time
 from os import path
-from typing import TYPE_CHECKING, Any, Iterable, Sequence
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
-from docutils.nodes import Node
 from docutils.utils import DependencyList
 
-from sphinx.config import Config
 from sphinx.environment import CONFIG_CHANGED_REASON, CONFIG_OK, BuildEnvironment
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import SphinxError
-from sphinx.events import EventManager
 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
+from sphinx.util.console import bold  # type: ignore[attr-defined]
 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
 from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath
 from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, parallel_available
-from sphinx.util.tags import Tags
-from sphinx.util.typing import NoneType
 
 # side effect: registers roles and directives
 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
+
+    from docutils.nodes import Node
+
     from sphinx.application import Sphinx
+    from sphinx.config import Config
+    from sphinx.events import EventManager
+    from sphinx.util.tags import Tags
+    from sphinx.util.typing import NoneType
 
 
 logger = logging.getLogger(__name__)
@@ -260,7 +263,7 @@ class Builder:
                                filename)
                 continue
 
-            if not filename.startswith(self.srcdir):
+            if not filename.startswith(str(self.srcdir)):
                 logger.warning(__('file %r given on command line is not under the '
                                   'source directory, ignoring'), filename)
                 continue
@@ -322,9 +325,9 @@ class Builder:
         if updated_docnames:
             # save the environment
             from sphinx.application import ENV_PICKLE_FILENAME
-            with progress_message(__('pickling environment')):
-                with open(path.join(self.doctreedir, ENV_PICKLE_FILENAME), 'wb') as f:
-                    pickle.dump(self.env, f, pickle.HIGHEST_PROTOCOL)
+            with progress_message(__('pickling environment')), \
+                    open(path.join(self.doctreedir, ENV_PICKLE_FILENAME), 'wb') as f:
+                pickle.dump(self.env, f, pickle.HIGHEST_PROTOCOL)
 
             # global actions
             self.app.phase = BuildPhase.CONSISTENCY_CHECK
@@ -488,7 +491,8 @@ class Builder:
         publisher.settings.record_dependencies = DependencyList()
         with sphinx_domains(self.env), rst.default_role(docname, self.config.default_role):
             # set up error_handler for the target document
-            codecs.register_error('sphinx', UnicodeDecodeErrorHandler(docname))  # type: ignore
+            codecs.register_error('sphinx',
+                                  UnicodeDecodeErrorHandler(docname))  # type: ignore[arg-type]
 
             publisher.set_source(source_path=filename)
             publisher.publish()

sphinx/builders/_epub_base.py

@@ -5,13 +5,13 @@ from __future__ import annotations
 import html
 import os
 import re
+import time
 from os import path
-from typing import Any, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple
 from urllib.parse import quote
 from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
 
 from docutils import nodes
-from docutils.nodes import Element, Node
 from docutils.utils import smartquotes
 
 from sphinx import addnodes
@@ -20,8 +20,10 @@ from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.display import status_iterator
 from sphinx.util.fileutil import copy_asset_file
-from sphinx.util.i18n import format_date
-from sphinx.util.osutil import copyfile, ensuredir
+from sphinx.util.osutil import copyfile, ensuredir, relpath
+
+if TYPE_CHECKING:
+    from docutils.nodes import Element, Node
 
 try:
     from PIL import Image
@@ -100,8 +102,7 @@ class NavPoint(NamedTuple):
     playorder: int
     text: str
     refuri: str
-    children: list[Any]     # mypy does not support recursive types
-                            # https://github.com/python/mypy/issues/7069
+    children: list[NavPoint]
 
 
 def sphinx_smarty_pants(t: str, language: str = 'en') -> str:
@@ -479,6 +480,12 @@ 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:
+            time_tuple = time.gmtime()
+
         metadata: dict[str, Any] = {}
         metadata['title'] = html.escape(self.config.epub_title)
         metadata['author'] = html.escape(self.config.epub_author)
@@ -488,7 +495,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         metadata['copyright'] = html.escape(self.config.epub_copyright)
         metadata['scheme'] = html.escape(self.config.epub_scheme)
         metadata['id'] = html.escape(self.config.epub_identifier)
-        metadata['date'] = html.escape(format_date("%Y-%m-%d", language='en'))
+        metadata['date'] = html.escape(time.strftime('%Y-%m-%d', time_tuple))
         metadata['manifest_items'] = []
         metadata['spines'] = []
         metadata['guides'] = []
@@ -502,9 +509,6 @@ class EpubBuilder(StandaloneHTMLBuilder):
         metadata = self.content_metadata()
 
         # files
-        if not self.outdir.endswith(os.sep):
-            self.outdir += os.sep
-        olen = len(self.outdir)
         self.files: list[str] = []
         self.ignored_files = ['.buildinfo', 'mimetype', 'content.opf',
                               'toc.ncx', 'META-INF/container.xml',
@@ -516,7 +520,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         for root, dirs, files in os.walk(self.outdir):
             dirs.sort()
             for fn in sorted(files):
-                filename = path.join(root, fn)[olen:]
+                filename = relpath(path.join(root, fn), self.outdir)
                 if filename in self.ignored_files:
                     continue
                 ext = path.splitext(filename)[-1]

sphinx/builders/changes.py

@@ -4,19 +4,21 @@ from __future__ import annotations
 
 import html
 from os import path
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from sphinx import package_dir
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 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
+from sphinx.util.console import bold  # type: ignore[attr-defined]
 from sphinx.util.fileutil import copy_asset_file
 from sphinx.util.osutil import ensuredir, os_path
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 
@@ -34,7 +36,7 @@ class ChangesBuilder(Builder):
         self.templates.init(self, self.theme)
 
     def get_outdated_docs(self) -> str:
-        return self.outdir
+        return str(self.outdir)
 
     typemap = {
         'versionadded': 'added',

sphinx/builders/dirhtml.py

@@ -3,13 +3,15 @@
 from __future__ import annotations
 
 from os import path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from sphinx.application import Sphinx
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.util import logging
 from sphinx.util.osutil import SEP, os_path
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 logger = logging.getLogger(__name__)
 
 

sphinx/builders/dummy.py

@@ -2,14 +2,16 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from docutils.nodes import Node
-
-from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.locale import __
 
+if TYPE_CHECKING:
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+
 
 class DummyBuilder(Builder):
     name = 'dummy'