Merge branch 'master' into issue-13096/html-search-handle-proto-query

.github/workflows/builddoc.yml

@@ -27,7 +27,7 @@ jobs:
       with:
         python-version: "3"
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
       run: >
         curl --no-progress-meter --location --fail

.github/workflows/main.yml

@@ -54,7 +54,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
       run: >
         curl --no-progress-meter --location --fail
@@ -92,7 +92,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -125,7 +125,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -158,7 +158,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -218,7 +218,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
       run: >
         curl --no-progress-meter --location --fail
@@ -250,7 +250,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
       run: >
         curl --no-progress-meter --location --fail
@@ -310,7 +310,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install graphviz
-      run: sudo apt-get install graphviz
+      run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
       run: >
         curl --no-progress-meter --location --fail

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
@@ -52,6 +51,7 @@ Contributors
 * Hugo van Kemenade -- support FORCE_COLOR and NO_COLOR
 * Ian Lee -- quickstart improvements
 * Jacob Mason -- websupport library (GSOC project)
+* James Addison -- linkcheck and HTML search improvements
 * Jeppe Pihl -- literalinclude improvements
 * Joel Wurtz -- cellspanning support in LaTeX
 * John Waltman -- Texinfo builder
@@ -72,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/conf.py

@@ -173,7 +173,6 @@
 }
 
 # Sphinx document translation with sphinx gettext feature uses these settings:
-locale_dirs = ['locale/']
 gettext_compact = False
 
 nitpick_ignore = {

doc/development/html_themes/index.rst

@@ -203,10 +203,10 @@ using the :meth:`~sphinx.application.Sphinx.add_html_theme` API:
 .. code-block:: python
 
     # your_theme_package.py
-    from os import path
+    from pathlib import Path
 
     def setup(app):
-        app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
+        app.add_html_theme('name_of_theme', Path(__file__).resolve().parent)
 
 If your theme package contains two or more themes, please call
 ``add_html_theme()`` twice or more.

doc/development/tutorials/extending_build.rst

@@ -313,10 +313,10 @@ For example:
 
 .. code-block:: python
 
-   import os
    import sys
+   from pathlib import Path
 
-   sys.path.append(os.path.abspath("./_ext"))
+   sys.path.append(str(Path('_ext').resolve()))
 
    extensions = ['todo']
 

doc/development/tutorials/extending_syntax.rst

@@ -169,10 +169,10 @@ For example:
 
 .. code-block:: python
 
-   import os
    import sys
+   from pathlib import Path
 
-   sys.path.append(os.path.abspath("./_ext"))
+   sys.path.append(str(Path('_ext').resolve()))
 
    extensions = ['helloworld']
 

doc/extdev/i18n.rst

@@ -51,7 +51,7 @@ In practice, you have to:
       :caption: src/__init__.py
 
       def setup(app):
-          package_dir = Path(__file__).parent.resolve()
+          package_dir = Path(__file__).resolve().parent
           locale_dir = package_dir / 'locales'
           app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
 

doc/tutorial/describing-code.rst

@@ -145,9 +145,9 @@ at the beginning of ``conf.py``:
 
    # If extensions (or modules to document with autodoc) are in another directory,
    # add these directories to sys.path here.
-   import pathlib
    import sys
-   sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+   from pathlib import Path
+   sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 
 .. note::
 

doc/usage/configuration.rst

@@ -223,11 +223,14 @@ General configuration
 
    Ensure that absolute paths are used when modifying :data:`sys.path`.
    If your custom extensions live in a directory that is relative to the
-   :term:`configuration directory`, use :func:`os.path.abspath` like so:
+   :term:`configuration directory`, use :meth:`pathlib.Path.resolve` like so:
 
    .. code-block:: python
 
-      import os, sys; sys.path.append(os.path.abspath('sphinxext'))
+      import sys
+      from pathlib import Path
+
+      sys.path.append(str(Path('sphinxext').resolve()))
 
       extensions = [
          ...

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

doc/usage/extensions/index.rst

@@ -69,11 +69,14 @@ Where to put your own extensions?
 Extensions local to a project should be put within the project's directory
 structure.  Set Python's module search path, ``sys.path``, accordingly so that
 Sphinx can find them.  For example, if your extension ``foo.py`` lies in the
-``exts`` subdirectory of the project root, put into :file:`conf.py`::
+``exts`` subdirectory of the project root, put into :file:`conf.py`:
 
-   import sys, os
+.. code-block:: python
 
-   sys.path.append(os.path.abspath('exts'))
+   import sys
+   from pathlib import Path
+
+   sys.path.append(str(Path('exts').resolve()))
 
    extensions = ['foo']
 

pyproject.toml

@@ -70,6 +70,7 @@ dependencies = [
     "alabaster>=0.7.14",
     "imagesize>=1.3",
     "requests>=2.30.0",
+    "roman-numerals-py>=1.0.0",
     "packaging>=23.0",
     "colorama>=0.4.6; sys_platform == 'win32'",
 ]
@@ -81,7 +82,7 @@ docs = [
 ]
 lint = [
     "flake8>=6.0",
-    "ruff==0.7.0",
+    "ruff==0.7.2",
     "mypy==1.13.0",
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
@@ -91,7 +92,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/_cli/__init__.py

@@ -170,7 +170,7 @@ def _format_metavar(
     def error(self, message: str) -> NoReturn:
         sys.stderr.write(
             __(
-                '{0}: error: {1}\n' "Run '{0} --help' for information"  # NoQA: COM812
+                "{0}: error: {1}\nRun '{0} --help' for information"  # NoQA: COM812
             ).format(self.prog, message)
         )
         raise SystemExit(2)