Merge branch 'main' into dependency-specifiers-grammar-fixes

.git-blame-ignore-revs

@@ -0,0 +1 @@
+1d7b1abd152e4cb5e6a46e52e6b7e3bf8d366486

.github/sphinx_lint_matcher.json

@@ -0,0 +1,15 @@
+{
+    "problemMatcher": [
+        {
+            "owner": "sphinx-lint-problem-matcher",
+            "pattern": [
+                {
+                    "regexp": "^(.*):(\\d+):\\s+(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "message": 3
+                }
+            ]
+        }
+    ]
+}

.github/workflows/cron.yml

@@ -0,0 +1,14 @@
+---
+
+name: Cron
+
+on:
+  schedule:
+  - cron: "0 6 * * *"  # daily at 6am
+
+jobs:
+  test:
+    if: github.repository_owner == 'pypa'  # suppress noise in forks
+    uses: ./.github/workflows/test.yml
+
+...

.github/workflows/pr-preview-links.yml

@@ -0,0 +1,22 @@
+name: Read the Docs PR preview
+
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "python-packaging-user-guide"

.github/workflows/test-translations.yml

@@ -0,0 +1,81 @@
+name: Test translations
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+    - '**.po'
+    branches:
+    - translation/source
+  push:
+    paths:
+    - '**.po'
+    branches:
+    - translation/source
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  I18N_BRANCH: translation/source
+
+jobs:
+  matrix:
+    runs-on: ubuntu-latest
+    outputs:
+      languages: ${{ steps.languages.outputs.languages }}
+
+    steps:
+    - name: Grab the repo src
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.I18N_BRANCH }}
+
+    - name: List languages
+      id: languages
+      working-directory: locales
+      run: |
+        list=$(find * -maxdepth 0 -type d | jq -nRc '[inputs]')
+        echo "languages=$list" >> $GITHUB_OUTPUT
+
+
+  test-translation:
+    runs-on: ubuntu-latest
+    needs: matrix
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ${{fromJson(needs.matrix.outputs.languages)}}
+
+    steps:
+    - name: Grab the repo src
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.I18N_BRANCH }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: >-
+          3.10
+
+    - name: Install Python tooling
+      run: python -m pip install --upgrade nox virtualenv sphinx-lint
+
+    - name: Set Sphinx problem matcher
+      uses: sphinx-doc/github-problem-matcher@v1.0
+
+    - name: Build translated docs in ${{ matrix.language }}
+      run: nox -s build -- -q -D language=${{ matrix.language }}
+
+    - name: Set Sphinx Lint problem matcher
+      if: always()
+      run: echo '::add-matcher::.github/sphinx_lint_matcher.json'
+
+    - name: Lint translation file
+      if: always()
+      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po

.github/workflows/test.yml

@@ -1,10 +1,12 @@
 name: Test
 
-on: 
+on:
+  merge_group:
   push:
+    branches-ignore:
+    - gh-readonly-queue/**  # Temporary merge queue-related GH-made branches
   pull_request:
-  schedule:
-    - cron: "0 6 * * *" # daily at 6am
+  workflow_call:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
@@ -13,6 +15,7 @@ concurrency:
 jobs:
   build:
     name: ${{ matrix.noxenv }}
+    if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -26,7 +29,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.11"
           cache: 'pip'
           cache-dependency-path: 'requirements.txt'
 
@@ -37,3 +40,21 @@ jobs:
       - name: Nox ${{ matrix.noxenv }}
         run: |
           python -m nox -s ${{ matrix.noxenv }}
+
+
+  check:
+    # This job does nothing and is only used for the branch protection
+    # or multi-stage CI jobs, like making sure that all tests pass before
+    # a publishing job is started.
+    if: always()
+
+    needs:
+    - build
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

.github/workflows/translation.yml

@@ -15,6 +15,7 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
+    if: github.repository_owner == 'pypa'
 
     steps:
     - name: Grab the repo src
@@ -65,6 +66,7 @@ jobs:
       run: |
         git_hash=$(git rev-parse --short "${GITHUB_SHA}")
         git add --force locales/messages.pot
+        git diff-index --quiet HEAD || \
         git commit \
           -m "Update messages.pot as of version ${git_hash}" \
           locales/messages.pot

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.6.0
+  hooks:
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-merge-conflict
+  - id: check-symlinks
+  - id: check-yaml
+  - id: end-of-file-fixer
+  - id: mixed-line-ending
+  - id: trailing-whitespace
+
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.2.6
+  hooks:
+  - id: codespell
+    args: ["-L", "ned,ist,oder", "--skip", "*.po"]
+
+- repo: local
+  hooks:
+  - id: disallow-caps
+    name: Disallow improper capitalization
+    language: pygrep
+    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
+    exclude: .pre-commit-config.yaml
+    exclude_types: ["pofile"]
+
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: v1.10.0
+  hooks:
+  - id: rst-backticks
+  - id: rst-directive-colons
+  - id: rst-inline-touching-normal
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.4.3
+  hooks:
+    - id: ruff
+    - id: ruff-format

.readthedocs.yaml

@@ -9,7 +9,11 @@ sphinx:
    # https://github.com/pyca/cryptography/issues/5863#issuecomment-792343136
    builder: dirhtml
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 python:
-   version: 3.8
    install:
    - requirements: requirements.txt

noxfile.py

@@ -3,9 +3,8 @@
 # Attribution-ShareAlike license:
 #   http://creativecommons.org/licenses/by-sa/3.0.
 
-import shutil
-import nox
 
+import nox
 
 nox.options.sessions = []
 
@@ -18,27 +17,26 @@ def translation(session):
     session.install("-r", "requirements.txt")
     target_dir = "locales"
     session.run(
-        "sphinx-build", 
-        "-b", "gettext",  # build gettext-style message catalogs (.pot file)
-        "-d", ".nox/.doctrees/", # path to put the cache
+        "sphinx-build",
+        "-b",
+        "gettext",  # build gettext-style message catalogs (.pot file)
+        "-d",
+        session.cache_dir / ".doctrees",  # path to put the cache
         "source/",  # where the rst files are located
-        target_dir, # where to put the .pot file
+        target_dir,  # where to put the .pot file
     )
 
+
 @nox.session()
 def build(session, autobuild=False):
     """
     Make the website.
     """
     session.install("-r", "requirements.txt")
 
-    target_build_dir = "build"
-
-    shutil.rmtree(target_build_dir, ignore_errors=True)
-
     if autobuild:
         command = "sphinx-autobuild"
-        extra_args = "-H", "0.0.0.0"
+        extra_args = "--host", "0.0.0.0"
     else:
         # NOTE: This branch adds options that are unsupported by autobuild
         command = "sphinx-build"
@@ -48,14 +46,19 @@ def build(session, autobuild=False):
         )
 
     session.run(
-        command, *extra_args,
-        "-j", "auto",  # parallelize the build
-        "-b", "html",  # use HTML builder
+        command,
+        *extra_args,
+        "-j",
+        "auto",  # parallelize the build
+        "-b",
+        "html",  # use HTML builder
+        "-d",
+        session.cache_dir / ".doctrees",  # path to put the cache
         "-n",  # nitpicky warn about all missing references
         "-W",  # Treat warnings as errors.
         *session.posargs,
         "source",  # where the rst files are located
-        target_build_dir,  # where to put the html output
+        "build",  # where to put the html output
     )
 
 
@@ -75,10 +78,29 @@ def linkcheck(session):
     """
     session.install("-r", "requirements.txt")
     session.run(
-        "sphinx-build", 
-        "-b", "linkcheck", # use linkcheck builder
+        "sphinx-build",
+        "-b",
+        "linkcheck",  # use linkcheck builder
+        "-d",
+        session.cache_dir / ".doctrees",  # path to put the cache
         "--color",
-        "-n", "-W", "--keep-going",  # be strict
-        "source", # where the rst files are located
-        "build", # where to put the check output
+        "-n",
+        "-W",
+        "--keep-going",  # be strict
+        "source",  # where the rst files are located
+        "build",  # where to put the check output
+    )
+
+
+@nox.session()
+def checkqa(session):
+    """
+    Format the guide using pre-commit.
+    """
+    session.install("pre-commit")
+    session.run(
+        "pre-commit",
+        "run",
+        "--all-files",
+        "--show-diff-on-failure",
     )

requirements.txt

@@ -1,6 +1,6 @@
-sphinx==4.5.0
-sphinx-autobuild==0.7.1
-sphinx-inline-tabs==2021.4.11b9
-python-docs-theme==2022.1
-sphinx-copybutton==0.5.0
-git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme
+furo==2023.9.10
+sphinx==7.2.6
+sphinx-autobuild==2021.3.14
+sphinx-inline-tabs==2023.4.21
+sphinx-copybutton==0.5.2
+sphinx-toolbox==3.5.0