Merge branch 'master' into latex_fontawesome6

Author: jfbu

.github/workflows/builddoc.yml

@@ -31,7 +31,7 @@ jobs:
     - name: Install graphviz
       run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false

.github/workflows/create-release.yml

@@ -35,7 +35,7 @@ jobs:
         with:
           python-version: "3"
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v6
         with:
           version: latest
           enable-cache: false
@@ -47,8 +47,7 @@ jobs:
         run: python -m build
 
       - name: Check distribution
-        run: |
-          twine check dist/*
+        run: twine check dist/*
 
       - name: Create Sigstore attestations for built distributions
         uses: actions/attest@v1
@@ -87,39 +86,10 @@ jobs:
           name: attestation-bundles
           path: /tmp/attestation-bundles/
 
-      - name: Mint PyPI API token
-        id: mint-token
-        uses: actions/github-script@v7
-        with:
-          # language=JavaScript
-          script: |
-            // retrieve the ambient OIDC token
-            const oidc_request_token = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
-            const oidc_request_url = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
-            const oidc_resp = await fetch(`${oidc_request_url}&audience=pypi`, {
-              headers: {Authorization: `bearer ${oidc_request_token}`},
-            });
-            const oidc_token = (await oidc_resp.json()).value;
-
-            // exchange the OIDC token for an API token
-            const mint_resp = await fetch('https://pypi.org/_/oidc/github/mint-token', {
-              method: 'post',
-              body: `{"token": "${oidc_token}"}` ,
-              headers: {'Content-Type': 'application/json'},
-            });
-            const api_token = (await mint_resp.json()).token;
-
-            // mask the newly minted API token, so that we don't accidentally leak it
-            core.setSecret(api_token)
-            core.setOutput('api-token', api_token)
-
       - name: Upload to PyPI
         env:
           TWINE_NON_INTERACTIVE: "true"
-          TWINE_USERNAME: "__token__"
-          TWINE_PASSWORD: "${{ steps.mint-token.outputs.api-token }}"
-        run: |
-          twine upload dist/* --attestations
+        run: twine upload dist/* --attestations
 
   github-release:
     runs-on: ubuntu-latest

.github/workflows/lint.yml

@@ -50,7 +50,7 @@ jobs:
       with:
         python-version: "3"
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -71,7 +71,7 @@ jobs:
       with:
         python-version: "3"
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -92,7 +92,7 @@ jobs:
       with:
         python-version: "3"
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -113,7 +113,7 @@ jobs:
       with:
         python-version: "3"
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false

.github/workflows/main.yml

@@ -37,6 +37,7 @@ jobs:
         - "3.11"
         - "3.12"
         - "3.13"
+        - "3.13t"
         docutils:
         - "0.20"
         - "0.21"
@@ -62,14 +63,18 @@ jobs:
     - name: Install graphviz
       run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
     - name: Install dependencies
       run: uv pip install . --group test
+      env:
+        UV_PYTHON: "python${{ matrix.python }}"
     - name: Install Docutils ${{ matrix.docutils }}
       run: uv pip install --upgrade "docutils~=${{ matrix.docutils }}.0"
+      env:
+        UV_PYTHON: "python${{ matrix.python }}"
     - name: Test with pytest
       run: python -m pytest -n logical --dist=worksteal -vv --durations 25
       env:
@@ -103,46 +108,14 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install .[test]
+        python -m pip install . --group test
     - name: Install Docutils ${{ matrix.docutils }}
       run: python -m pip install --upgrade "docutils~=${{ matrix.docutils }}.0"
     - name: Test with pytest
       run: python -m pytest -n logical --dist=worksteal -vv --durations 25
       env:
         PYTHONWARNINGS: "error"  # treat all warnings as errors
 
-  free-threaded:
-    runs-on: ubuntu-latest
-    name: Python ${{ matrix.python }} (free-threaded)
-    timeout-minutes: 15
-    strategy:
-      fail-fast: false
-      matrix:
-        python:
-        - "3.13"
-
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        persist-credentials: false
-    - name: Set up Python ${{ matrix.python }} (deadsnakes)
-      uses: deadsnakes/[email protected]
-      with:
-        python-version: ${{ matrix.python }}
-        nogil: true
-    - name: Check Python version
-      run: python --version --version
-    - name: Install graphviz
-      run: sudo apt-get install --no-install-recommends --yes graphviz
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install .[test]
-    - name: Test with pytest
-      run: python -m pytest -n logical --dist=worksteal -vv --durations 25
-      env:
-        PYTHONWARNINGS: "error"  # treat all warnings as errors
-
   deadsnakes-free-threaded:
     runs-on: ubuntu-latest
     name: Python ${{ matrix.python }} (free-threaded)
@@ -169,7 +142,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install .[test]
+        python -m pip install . --group test
     - name: Test with pytest
       run: python -m pytest -n logical --dist=worksteal -vv --durations 25
       env:
@@ -181,6 +154,14 @@ jobs:
     timeout-minutes: 15
 
     steps:
+    # https://github.com/actions/runner-images/issues/8755
+    # On standard runners, the D: drive is much faster.
+    - name: Set %TMP% and %TEMP% to D:\\Temp
+      run: |
+        mkdir "D:\\Tmp"
+        echo "TMP=D:\\Tmp" >> $env:GITHUB_ENV
+        echo "TEMP=D:\\Tmp" >> $env:GITHUB_ENV
+
     - uses: actions/checkout@v4
       with:
         persist-credentials: false
@@ -193,7 +174,7 @@ jobs:
     - name: Install graphviz
       run: choco install --no-progress graphviz
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -222,7 +203,7 @@ jobs:
     - name: Install graphviz
       run: brew install graphviz
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -257,7 +238,7 @@ jobs:
     - name: Install graphviz
       run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -290,7 +271,7 @@ jobs:
     - name: Install graphviz
       run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -321,7 +302,7 @@ jobs:
     - name: Check Python version
       run: python --version --version
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -352,7 +333,7 @@ jobs:
     - name: Install graphviz
       run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false

.github/workflows/transifex.yml

@@ -36,7 +36,7 @@ jobs:
         curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
       shell: bash
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false
@@ -72,7 +72,7 @@ jobs:
         curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
       shell: bash
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v6
       with:
         version: latest
         enable-cache: false

AUTHORS.rst

@@ -102,6 +102,7 @@ Contributors
 * Slawek Figiel -- additional warning suppression
 * Stefan Seefeld -- toctree improvements
 * Stefan van der Walt -- autosummary extension
+* Steve Piercy -- documentation improvements
 * \T. Powers -- HTML output improvements
 * Taku Shimizu -- epub3 builder
 * Thomas Lamb -- linkcheck builder

doc/extdev/markupapi.rst

@@ -173,9 +173,9 @@ The methods are used as follows:
       def run(self) -> list[Node]:
           container = docutils.nodes.Element()
           # either
-          nested_parse_with_titles(self.state, self.result, container)
+          nested_parse_with_titles(self.state, self.result, container, self.content_offset)
           # or
-          self.state.nested_parse(self.result, 0, container)
+          self.state.nested_parse(self.result, self.content_offset, container)
           parsed = container.children
           return parsed
 

doc/latex.rst

@@ -500,7 +500,7 @@ Keys that don't need to be overridden unless in special cases are:
    .. hint::
 
       If the key value is set to
-      :code-tex:`r'\\newcommand\sphinxbackoftitlepage{<Extra
+      :code-tex:`'\\newcommand\\sphinxbackoftitlepage{<Extra
       material>}\\sphinxmaketitle'`, then ``<Extra material>`` will be
       typeset on back of title page (``'manual'`` docclass only).
 
@@ -1696,7 +1696,7 @@ Macros
   .. hint::
 
      If adding to preamble the loading of ``tocloft`` package, also add to
-     preamble :code-tex:`\\renewcommand\sphinxtableofcontentshook{}` else it
+     preamble :code-tex:`\\renewcommand\\sphinxtableofcontentshook{}` else it
      will reset :code-tex:`\\l@section` and :code-tex:`\\l@subsection`
      cancelling ``tocloft`` customization.
 

doc/man/sphinx-build.rst

@@ -272,13 +272,13 @@ Options
    From Sphinx 8.1, :option:`!--keep-going` is always enabled.
    Previously, it was only applicable whilst using :option:`--fail-on-warning`,
    which by default exited :program:`sphinx-build` on the first warning.
-   Using :option:`!--keep-going` runs :program:`!sphinx-build` to completion
+   Using :option:`!--keep-going` runs :program:`sphinx-build` to completion
    and exits with exit status 1 if errors are encountered.
 
    .. versionadded:: 1.8
    .. versionchanged:: 8.1
       :program:`sphinx-build` no longer exits on the first warning,
-      meaning that in effect :option:`!--fail-on-warning` is always enabled.
+      meaning that in effect :option:`!--keep-going` is always enabled.
       The option is retained for compatibility, but may be removed at some
       later date.
 

doc/usage/configuration.rst

@@ -3668,7 +3668,7 @@ and which failures and redirects it ignores.
    .. versionadded:: 4.1
 
    .. versionchanged:: 8.3
-      Setting :confval:`!linkcheck_allowed_redirects` to the empty directory
+      Setting :confval:`!linkcheck_allowed_redirects` to an empty dictionary
       may now be used to warn on all redirects encountered
       by the *linkcheck* builder.
 

pyproject.toml

@@ -92,7 +92,7 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.11.2",
+    "ruff==0.11.9",
     "mypy==1.15.0",
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
@@ -102,9 +102,9 @@ lint = [
     "types-Pygments==2.19.0.20250305",
     "types-requests==2.32.0.20250328",  # align with requests
     "types-urllib3==1.26.25.14",
-    "pyright==1.1.397",
+    "pyright==1.1.400",
     "pytest>=8.0",
-    "pypi-attestations==0.0.22",
+    "pypi-attestations==0.0.25",
     "betterproto==2.0.0b6",
 ]
 test = [
@@ -135,14 +135,14 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.11.2",
+    "ruff==0.11.9",
     "sphinx-lint>=0.9",
 ]
 package = [
     "betterproto==2.0.0b6",  # resolution fails without betterproto
     "build",
-    "pypi-attestations==0.0.22",
-    "twine>=5.1",
+    "pypi-attestations==0.0.25",
+    "twine>=6.1",
 ]
 test = [
     "pytest>=8.0",
@@ -158,7 +158,7 @@ translations = [
 ]
 types = [
     "mypy==1.15.0",
-    "pyright==1.1.397",
+    "pyright==1.1.400",
     { include-group = "type-stubs" },
 ]
 type-stubs = [
@@ -290,7 +290,6 @@ module = [
     "tests.test_util.test_util",
     "tests.test_util.test_util_display",
     "tests.test_util.test_util_docutils",
-    "tests.test_util.test_util_images",
     "tests.test_util.test_util_inventory",
     # tests/test_writers
     "tests.test_writers.test_docutilsconf",