Merge branch 'master' into doc-doctest

Author: timhoffm

AUTHORS.rst

@@ -8,7 +8,7 @@ Maintainers
 * Chris Sewell <@chrisjsewell>
 * François Freitag <@francoisfreitag>
 * Jakob Lykke Andersen <@jakobandersen>
-* Jean-François Burnol <@jfbu>
+* Jean-François B. <@jfbu>
 * Stephen Finucane <@stephenfin>
 * Takayuki Shimizukawa <@shimizukawa>
 * Takeshi Komiya <@tk0miya>
@@ -35,7 +35,6 @@ Contributors
 * Christopher Perkins -- autosummary integration
 * Dan MacKinlay -- metadata fixes
 * Daniel Bültmann -- todo extension
-* Daniel Neuhäuser -- JavaScript domain, Python 3 support (GSOC)
 * Daniel Pizetta -- inheritance diagram improvements
 * Dave Kuhlman -- original LaTeX writer
 * Doug Hellmann -- graphviz improvements
@@ -73,14 +72,12 @@ Contributors
 * Michael Wilson -- Intersphinx HTTP basic auth support
 * Nathan Damon -- bugfix in validation of static paths in html builders
 * Pauli Virtanen -- autodoc improvements, autosummary extension
-* A. Rafey Khan -- improved intersphinx typing
-* Rob Ruana -- napoleon extension
-* Robert Lehmann -- gettext builder (GSOC project)
+* \A. Rafey Khan -- improved intersphinx typing
 * Roland Meister -- epub builder
 * Sebastian Wiesner -- image handling, distutils support
 * Stefan Seefeld -- toctree improvements
 * Stefan van der Walt -- autosummary extension
-* T. Powers -- HTML output improvements
+* \T. Powers -- HTML output improvements
 * Taku Shimizu -- epub3 builder
 * Thomas Lamb -- linkcheck builder
 * Thomas Waldmann -- apidoc module fixes

doc/usage/extensions/autosummary.rst

@@ -61,63 +61,67 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
    :event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
    hooks as :mod:`~sphinx.ext.autodoc`.
 
-   **Options**
+   .. rubric:: Options
 
-   * If you want the :rst:dir:`autosummary` table to also serve as a
-     :rst:dir:`toctree` entry, use the ``toctree`` option, for example::
+   .. rst:directive:option:: toctree: optional directory name
+
+      If you want the :rst:dir:`autosummary` table to also serve as a
+      :rst:dir:`toctree` entry, use the ``toctree`` option, for example::
 
          .. autosummary::
             :toctree: DIRNAME
 
             sphinx.environment.BuildEnvironment
             sphinx.util.relative_uri
 
-     The ``toctree`` option also signals to the :program:`sphinx-autogen` script
-     that stub pages should be generated for the entries listed in this
-     directive.  The option accepts a directory name as an argument;
-     :program:`sphinx-autogen` will by default place its output in this
-     directory. If no argument is given, output is placed in the same directory
-     as the file that contains the directive.
+      The ``toctree`` option also signals to the :program:`sphinx-autogen` script
+      that stub pages should be generated for the entries listed in this
+      directive.  The option accepts a directory name as an argument;
+      :program:`sphinx-autogen` will by default place its output in this
+      directory. If no argument is given, output is placed in the same directory
+      as the file that contains the directive.
 
-     You can also use ``caption`` option to give a caption to the toctree.
+      .. versionadded:: 0.6
 
-     .. versionadded:: 3.1
+   .. rst:directive:option:: caption: caption of ToC
 
-        caption option added.
+      Add a caption to the toctree.
 
-   * If you don't want the :rst:dir:`autosummary` to show function signatures in
-     the listing, include the ``nosignatures`` option::
+      .. versionadded:: 3.1
 
-         .. autosummary::
-            :nosignatures:
+   .. rst:directive:option:: nosignatures
 
-            sphinx.environment.BuildEnvironment
-            sphinx.util.relative_uri
+      Do not show function signatures in the summary.
 
-   * You can specify a custom template with the ``template`` option.
-     For example, ::
+      .. versionadded:: 0.6
+
+   .. rst:directive:option:: template: filename
+
+      Specify a custom template for rendering the summary.
+      For example, ::
 
          .. autosummary::
             :template: mytemplate.rst
 
             sphinx.environment.BuildEnvironment
 
-     would use the template :file:`mytemplate.rst` in your
-     :confval:`templates_path` to generate the pages for all entries
-     listed. See `Customizing templates`_ below.
+      would use the template :file:`mytemplate.rst` in your
+      :confval:`templates_path` to generate the pages for all entries
+      listed. See `Customizing templates`_ below.
+
+      .. versionadded:: 1.0
 
-     .. versionadded:: 1.0
+   .. rst:directive:option:: recursive
 
-   * You can specify the ``recursive`` option to generate documents for
-     modules and sub-packages recursively.  It defaults to disabled.
-     For example, ::
+      Generate documents for modules and sub-packages recursively.
+      For example, ::
 
          .. autosummary::
             :recursive:
 
             sphinx.environment.BuildEnvironment
 
-     .. versionadded:: 3.1
+      .. versionadded:: 3.1
 
 
 :program:`sphinx-autogen` -- generate autodoc stub pages

pyproject.toml

@@ -91,7 +91,7 @@ lint = [
     "types-Pygments==2.18.0.20240506",
     "types-requests==2.32.0.20241016",  # align with requests
     "types-urllib3==1.26.25.14",
-    "pyright==1.1.387",
+    "pyright==1.1.388",
     "pytest>=6.0",
 ]
 test = [

sphinx/ext/viewcode.py

@@ -29,6 +29,7 @@
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
+    from sphinx.util._pathlib import _StrPath
     from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
@@ -207,7 +208,7 @@ def remove_viewcode_anchors(self) -> None:
             node.parent.remove(node)
 
 
-def get_module_filename(app: Sphinx, modname: str) -> str | None:
+def get_module_filename(app: Sphinx, modname: str) -> _StrPath | None:
     """Get module filename for *modname*."""
     source_info = app.emit_firstresult('viewcode-find-source', modname)
     if source_info:

sphinx/pycode/__init__.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-import os
-import os.path
 import tokenize
 from importlib import import_module
 from typing import TYPE_CHECKING, Any, Literal
@@ -13,6 +11,7 @@
 from sphinx.util._pathlib import _StrPath
 
 if TYPE_CHECKING:
+    import os
     from inspect import Signature
 
 
@@ -28,7 +27,7 @@ class ModuleAnalyzer:
     cache: dict[tuple[Literal['file', 'module'], str | _StrPath], Any] = {}
 
     @staticmethod
-    def get_module_source(modname: str) -> tuple[str | None, str | None]:
+    def get_module_source(modname: str) -> tuple[_StrPath | None, str | None]:
         """Try to find the source code for a module.
 
         Returns ('filename', 'source'). One of it can be None if
@@ -39,14 +38,15 @@ def get_module_source(modname: str) -> tuple[str | None, str | None]:
         except Exception as err:
             raise PycodeError('error importing %r' % modname, err) from err
         loader = getattr(mod, '__loader__', None)
-        filename = getattr(mod, '__file__', None)
+        filename: str | None = getattr(mod, '__file__', None)
         if loader and getattr(loader, 'get_source', None):
             # prefer Native loader, as it respects #coding directive
             try:
                 source = loader.get_source(modname)
                 if source:
+                    mod_path = None if filename is None else _StrPath(filename)
                     # no exception and not None - it must be module source
-                    return filename, source
+                    return mod_path, source
             except ImportError:
                 pass  # Try other "source-mining" methods
         if filename is None and loader and getattr(loader, 'get_filename', None):
@@ -60,24 +60,28 @@ def get_module_source(modname: str) -> tuple[str | None, str | None]:
         if filename is None:
             # all methods for getting filename failed, so raise...
             raise PycodeError('no source found for module %r' % modname)
-        filename = os.path.normpath(os.path.abspath(filename))
-        if filename.lower().endswith(('.pyo', '.pyc')):
-            filename = filename[:-1]
-            if not os.path.isfile(filename) and os.path.isfile(filename + 'w'):
-                filename += 'w'
-        elif not filename.lower().endswith(('.py', '.pyw')):
-            raise PycodeError('source is not a .py file: %r' % filename)
-
-        if not os.path.isfile(filename):
-            raise PycodeError('source file is not present: %r' % filename)
-        return filename, None
+        mod_path = _StrPath(filename).resolve()
+        if mod_path.suffix in {'.pyo', '.pyc'}:
+            mod_path_pyw = mod_path.with_suffix('.pyw')
+            if not mod_path.is_file() and mod_path_pyw.is_file():
+                mod_path = mod_path_pyw
+            else:
+                mod_path = mod_path.with_suffix('.py')
+        elif mod_path.suffix not in {'.py', '.pyw'}:
+            msg = f'source is not a .py file: {mod_path!r}'
+            raise PycodeError(msg)
+
+        if not mod_path.is_file():
+            msg = f'source file is not present: {mod_path!r}'
+            raise PycodeError(msg)
+        return mod_path, None
 
     @classmethod
     def for_string(
         cls: type[ModuleAnalyzer],
         string: str,
         modname: str,
-        srcname: str = '<string>',
+        srcname: str | os.PathLike[str] = '<string>',
     ) -> ModuleAnalyzer:
         return cls(string, modname, srcname)
 

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -32,7 +32,7 @@
 %   sphinxlatexshadowbox.sty, and handles both "with icon" and "without
 %   icon" situations).
 %
-% The sphinxlightbox environment is kept for backward compatiblity, for user
+% The sphinxlightbox environment is kept for backward compatibility, for user
 % custom code which used it via custom definitions done in preamble or via
 % raw latex directive.
 % MEMO: here is for example how sphinxnote was formerly defined:

sphinx/transforms/i18n.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import contextlib
-import os.path
 from re import DOTALL, match
 from textwrap import indent
 from typing import TYPE_CHECKING, Any, TypeVar
@@ -394,10 +393,8 @@ def apply(self, **kwargs: Any) -> None:
         textdomain = docname_to_domain(self.env.docname, self.config.gettext_compact)
 
         # fetch translations
-        dirs = [
-            os.path.join(self.env.srcdir, directory)
-            for directory in self.config.locale_dirs
-        ]
+        srcdir = self.env.srcdir
+        dirs = [srcdir / directory for directory in self.config.locale_dirs]
         catalog, has_catalog = init_locale(dirs, self.config.language, textdomain)
         if not has_catalog:
             return

sphinx/util/_pathlib.py

@@ -3,7 +3,7 @@
 Instances of _StrPath should not be constructed except in Sphinx itself.
 Consumers of Sphinx APIs should prefer using ``pathlib.Path`` objects
 where possible. _StrPath objects can be treated as equivalent to ``Path``,
-save that ``_StrPath.replace`` is overriden with ``str.replace``.
+save that ``_StrPath.replace`` is overridden with ``str.replace``.
 
 To continue treating path-like objects as strings, use ``os.fspath``,
 or explicit string coercion.

sphinx/util/logging.py

@@ -6,14 +6,14 @@
 import logging.handlers
 from collections import defaultdict
 from contextlib import contextmanager, nullcontext
+from os.path import abspath
 from typing import IO, TYPE_CHECKING, Any
 
 from docutils import nodes
 from docutils.utils import get_source_line
 
 from sphinx.errors import SphinxWarning
 from sphinx.util.console import colorize
-from sphinx.util.osutil import abspath
 
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence, Set

sphinx/writers/latex.py

@@ -6,10 +6,10 @@
 
 from __future__ import annotations
 
-import os.path
 import re
 from collections import defaultdict
 from collections.abc import Iterable
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes, writers
@@ -583,18 +583,19 @@ def generate(
     def render(self, template_name: str, variables: dict[str, Any]) -> str:
         renderer = LaTeXRenderer(latex_engine=self.config.latex_engine)
         for template_dir in self.config.templates_path:
-            template = os.path.join(self.builder.confdir, template_dir, template_name)
-            if os.path.exists(template):
-                return renderer.render(template, variables)
-            elif template.endswith('.jinja'):
-                legacy_template = template.removesuffix('.jinja') + '_t'
-                if os.path.exists(legacy_template):
+            template = self.builder.confdir / template_dir / template_name
+            if template.exists():
+                return renderer.render(str(template), variables)
+            elif template.suffix == '.jinja':
+                legacy_template_name = template.name.removesuffix('.jinja') + '_t'
+                legacy_template = template.with_name(legacy_template_name)
+                if legacy_template.exists():
                     logger.warning(
                         __('template %s not found; loading from legacy %s instead'),
                         template_name,
                         legacy_template,
                     )
-                    return renderer.render(legacy_template, variables)
+                    return renderer.render(str(legacy_template), variables)
 
         return renderer.render(template_name, variables)
 
@@ -1648,7 +1649,9 @@ def visit_image(self, node: Element) -> None:
         options = ''
         if include_graphics_options:
             options = '[%s]' % ','.join(include_graphics_options)
-        base, ext = os.path.splitext(uri)
+        img_path = Path(uri)
+        base = img_path.with_suffix('')
+        ext = img_path.suffix
 
         if self.in_title and base:
             # Lowercase tokens forcely because some fncychap themes capitalize
@@ -1657,8 +1660,8 @@ def visit_image(self, node: Element) -> None:
         else:
             cmd = rf'\sphinxincludegraphics{options}{{{{{base}}}{ext}}}'
         # escape filepath for includegraphics, https://tex.stackexchange.com/a/202714/41112
-        if '#' in base:
-            cmd = r'{\catcode`\#=12' + cmd + '}'
+        if '#' in str(base):
+            cmd = rf'{{\catcode`\#=12{cmd}}}'
         self.body.append(cmd)
         self.body.extend(post)