Fix linkcheck timeouts

.github/workflows/test.yml

@@ -24,6 +24,7 @@ jobs:
     name: ${{ matrix.noxenv }}
     if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     strategy:
       matrix:
         noxenv:
@@ -47,6 +48,9 @@ jobs:
           python -m pip install --upgrade nox virtualenv
 
       - name: Nox ${{ matrix.noxenv }}
+        env:
+          # Authenticate github.com requests during linkcheck to avoid rate limits.
+          GITHUB_TOKEN: ${{ github.token }}
         run: |
           python -m nox -s ${{ matrix.noxenv }}
 

source/conf.py

@@ -161,7 +161,8 @@
     # Ref: https://github.com/pypa/packaging.python.org/issues/1998
     r"https://blog\.ganssle\.io/.*",
 ]
-linkcheck_retries = 5
+linkcheck_retries = 2
+linkcheck_timeout = 30
 # Ignore anchors for common targets when we know they likely won't be found
 linkcheck_anchors_ignore_for_url = [
     # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
@@ -171,6 +172,13 @@
     # https://github.com/pypa/packaging.python.org/issues/1744
     r"https://pypi\.org/",
 ]
+# Authenticate requests to github.com (when a token is available) to avoid
+# unauthenticated rate limits that can stall linkcheck for hours on CI.
+if _gh_token := os.getenv("GITHUB_TOKEN"):
+    linkcheck_request_headers = {
+        "https://github.com/": {"Authorization": f"Bearer {_gh_token}"},
+        "https://api.github.com/": {"Authorization": f"Bearer {_gh_token}"},
+    }
 
 # -- Options for extlinks ----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration