Merge branch 'master' into feature-enhance-glossary-directive-doc

.gitattributes

@@ -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

.github/ISSUE_TEMPLATE/config.yml

@@ -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/PULL_REQUEST_TEMPLATE.md

@@ -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/workflows/builddoc.yml

@@ -22,18 +22,19 @@ jobs:
 
     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 --no-install-recommends --yes graphviz
     - name: Install uv
-      run: >
-        curl --no-progress-meter --location --fail
-        --proto '=https' --tlsv1.2
-        "https://astral.sh/uv/install.sh"
-        | sh
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: latest
+        enable-cache: false
     - name: Install dependencies
       run: uv pip install .[docs]
     - name: Render the documentation

.github/workflows/create-release.yml

@@ -28,22 +28,21 @@ jobs:
       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"
       - name: Install uv
-        run: >
-          curl --no-progress-meter --location --fail
-          --proto '=https' --tlsv1.2
-          "https://astral.sh/uv/install.sh"
-          | sh
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: latest
+          enable-cache: false
 
       - name: Install build dependencies (pypa/build, twine)
         run: |
           uv pip install build "twine>=5.1"
-          # resolution fails without betterproto and protobuf-specs
-          uv pip install "pypi-attestations~=0.0.12" "sigstore-protobuf-specs==0.3.2" "betterproto==2.0.0b6"
 
       - name: Build distribution
         run: python -m build
@@ -62,11 +61,15 @@ jobs:
           show-summary: "true"
 
       - name: Convert attestations to PEP 740
-        # workflow_ref example: sphinx-doc/sphinx/.github/workflows/create-release.yml@refs/heads/master
         run: >
-          python utils/convert_attestations.py
-          "${{ steps.attest.outputs.bundle-path }}"
-          "https://github.com/${{ github.workflow_ref }}"
+          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: |
@@ -75,8 +78,10 @@ jobs:
       - name: Prepare attestation bundles for uploading
         run: |
           mkdir -p /tmp/attestation-bundles
-          cp "${{ steps.attest.outputs.bundle-path }}" /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
@@ -97,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',
@@ -127,6 +132,8 @@ jobs:
       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