Merge branch 'master' into search-button

Author: AA-Turner

.flake8

@@ -0,0 +1,65 @@
+# Binary data types
+*.gif binary
+*.jpg binary
+*.mo  binary
+*.pdf binary
+*.png binary
+*.zip binary
+
+# Unix-style line endings
+[attr]unix text eol=lf
+
+*.conf  unix
+*.css   unix
+*.cls   unix
+*.csv   unix
+*.dot   unix
+*.html  unix
+*.inc   unix
+*.ini   unix
+*.jinja unix
+*.js    unix
+*.md    unix
+*.mjs   unix
+*.py    unix
+*.rst   unix
+*.sty   unix
+*.tex   unix
+*.toml  unix
+*.txt   unix
+*.svg   unix
+*.xml   unix
+*.yml   unix
+
+# CRLF files
+[attr]dos text eol=crlf
+
+*.bat       dos
+*.bat.jinja dos
+*.stp       dos
+tests/roots/test-pycode/cp_1251_coded.py dos
+
+# Language aware diff headers
+*.c    diff=cpp
+*.h    diff=cpp
+*.css  diff=css
+*.html diff=html
+*.md   diff=markdown
+*.py   diff=python
+# *.rst  diff=reStructuredText
+*.tex  diff=tex
+
+# Non UTF-8 encodings
+tests/roots/test-pycode/cp_1251_coded.py working-tree-encoding=windows-1251
+
+# Generated files
+# https://github.com/github/linguist/blob/master/docs/overrides.md
+#
+# To always hide generated files in local diffs, mark them as binary:
+# $ git config diff.generated.binary true
+#
+[attr]generated linguist-generated=true diff=generated
+
+tests/js/fixtures/**/*.js                           generated
+sphinx/search/minified-js/*.js                      generated
+sphinx/themes/bizstyle/static/css3-mediaqueries.js  generated

.gitattributes

@@ -5,5 +5,5 @@ contact_links:
   url: https://stackoverflow.com/questions/tagged/python-sphinx
   about: For Q&A purpose, please use Stackoverflow with the tag python-sphinx
 - name: Discussion
-  url: https://groups.google.com/forum/#!forum/sphinx-users
-  about: For general discussion, please use sphinx-users mailing list.
+  url: https://github.com/sphinx-doc/sphinx/discussions
+  about: For general discussion, please use GitHub Discussions.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,19 +1,33 @@
-Subject: <short purpose of this pull request>
+<!--
+Thank you for creating this pull request and for spending time to help Sphinx!
+Our contributors' guide can be found online: https://www.sphinx-doc.org/en/master/internals/contributing.html
+Ask any questions at https://github.com/sphinx-doc/sphinx/discussions
+-->
 
-### Feature or Bugfix
-<!-- please choose -->
-- Feature
-- Bugfix
-- Refactoring
 
-### Purpose
-- <long purpose of this pull request>
-- <Environment if this PR depends on>
+## Purpose
 
-### Detail
-- <feature1 or bug1>
-- <feature2 or bug2>
+<!--
+A description of the purpose of this pull request.
+Ensure that all relevant information is included for reviewers,
+including any environment-specific details.
 
-### Relates
-- <URL or Ticket>
+* If you plan to add tests or documentation after opening this PR,
+  please note it here.
+* For user-visible changes, remember to add an entry to CHANGES.rst.
+* Please add your name to AUTHORS.rst if you haven't already!
+-->
 
+
+## References
+
+<!--
+Please add any relevant links here, especially including any 
+GitHub issues or Pull Requests that this PR would resolve.
+This helps to ensure that reviewers have context from
+previous discussions or decisions.
+-->
+
+- <...>
+- <...>
+- <...>

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,29 +14,34 @@ concurrency:
 
 env:
   FORCE_COLOR: "1"
+  UV_SYSTEM_PYTHON: "1"  # make uv do global installs
 
 jobs:
-  build:
+  verbose:
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
     - name: Set up Python
       uses: actions/setup-python@v5
       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
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: latest
+        enable-cache: false
     - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install .[docs]
+      run: uv pip install .[docs]
     - name: Render the documentation
       run: >
         sphinx-build
         -M html ./doc ./build/sphinx
-        -vv
+        --verbose
         --jobs=auto
         --show-traceback
         --fail-on-warning
-        --keep-going

.github/workflows/builddoc.yml

@@ -9,30 +9,86 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1"
+  UV_SYSTEM_PYTHON: "1"  # make uv do global installs
+
 jobs:
   publish-pypi:
     runs-on: ubuntu-latest
     name: PyPI Release
     environment: release
+    if: github.repository_owner == 'sphinx-doc'
     permissions:
+      attestations: write  # for actions/attest
       id-token: write  # for PyPI trusted publishing
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3"
-          cache: pip
-          cache-dependency-path: pyproject.toml
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: latest
+          enable-cache: false
 
       - name: Install build dependencies (pypa/build, twine)
         run: |
-          pip install -U pip
-          pip install build twine
+          uv pip install build "twine>=5.1"
 
       - name: Build distribution
         run: python -m build
 
+      - name: Check distribution
+        run: |
+          twine check dist/*
+
+      - name: Create Sigstore attestations for built distributions
+        uses: actions/attest@v1
+        id: attest
+        with:
+          subject-path: "dist/*"
+          predicate-type: "https://docs.pypi.org/attestations/publish/v1"
+          predicate: "null"
+          show-summary: "true"
+
+      - name: Convert attestations to PEP 740
+        run: >
+          uv run utils/convert_attestations.py
+          "$BUNDLE_PATH"
+          "$SIGNER_IDENTITY"
+        env:
+          BUNDLE_PATH: "${{ steps.attest.outputs.bundle-path }}"
+          # workflow_ref example: sphinx-doc/sphinx/.github/workflows/create-release.yml@refs/heads/master
+          # this forms the "signer identity" for the attestations
+          SIGNER_IDENTITY: "https://github.com/${{ github.workflow_ref }}"
+
+      - name: Inspect PEP 740 attestations
+        run: |
+          python -m pypi_attestations inspect dist/*.publish.attestation
+
+      - name: Prepare attestation bundles for uploading
+        run: |
+          mkdir -p /tmp/attestation-bundles
+          cp "$BUNDLE_PATH" /tmp/attestation-bundles/
+          cp dist/*.publish.attestation /tmp/attestation-bundles/
+        env:
+          BUNDLE_PATH: "${{ steps.attest.outputs.bundle-path }}"
+
+      - name: Upload attestation bundles
+        uses: actions/upload-artifact@v4
+        with:
+          name: attestation-bundles
+          path: /tmp/attestation-bundles/
+
       - name: Mint PyPI API token
         id: mint-token
         uses: actions/github-script@v7
@@ -46,7 +102,7 @@ jobs:
               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',
@@ -65,17 +121,19 @@ jobs:
           TWINE_USERNAME: "__token__"
           TWINE_PASSWORD: "${{ steps.mint-token.outputs.api-token }}"
         run: |
-          twine check dist/*
-          twine upload dist/*
+          twine upload dist/* --attestations
 
   github-release:
     runs-on: ubuntu-latest
     name: GitHub release
     environment: release
+    if: github.repository_owner == 'sphinx-doc'
     permissions:
       contents: write  # for softprops/action-gh-release to create GitHub release
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - name: Get release version
         id: get_version
         uses: actions/github-script@v7