PYTHON-5393 Make link checking more robust

Author: blink1073

.github/workflows/test-python.yml

@@ -125,6 +125,8 @@ jobs:
   linkcheck:
     name: Link Check
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v4
         with:
@@ -139,6 +141,8 @@ jobs:
       - name: Install dependencies
         run: just install
       - name: Build docs
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: just docs-linkcheck
 
   typing:

doc/conf.py

@@ -4,6 +4,7 @@
 # This file is execfile()d with the current directory set to its containing dir.
 from __future__ import annotations
 
+import os
 import sys
 from pathlib import Path
 
@@ -91,6 +92,14 @@
     r"https://sourceforge.net/",
 ]
 
+# Add GitHub auth if available to avoid rate limiting.
+if "GH_TOKEN" in os.environ:
+    token = os.environ["GH_TOKEN"]
+    linkcheck_request_headers = {r"https://github.\.com/.+": {"authorization": f"Bearer ${token}"}}
+
+# Allow for flakey links.
+linkcheck_retries = 2
+
 # -- Options for extensions ----------------------------------------------------
 autoclass_content = "init"