From 4da083d4d7d00a2104ce93bb0d650536b2728585 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= <melissawm@gmail.com>
Date: Wed, 29 Apr 2026 20:09:59 -0300
Subject: [PATCH] Add weekly linkchecker and report failures on issue

---
 .github/workflows/check_docs_build.yml |  4 +-
 .github/workflows/linkcheck.yml        | 80 ++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 3 deletions(-)
 create mode 100644 .github/workflows/linkcheck.yml

diff --git a/.github/workflows/check_docs_build.yml b/.github/workflows/check_docs_build.yml
index e755ff27c5..7da545b0a1 100644
--- a/.github/workflows/check_docs_build.yml
+++ b/.github/workflows/check_docs_build.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -54,8 +54,6 @@ jobs:
           . $GITHUB_WORKSPACE/venv/bin/activate
           uv pip install -e . --no-deps
           uv pip install torch
-          # verify links; the build fails if errors are found
-          sphinx-build -b linkcheck docs docs/_build/linkcheck -q --keep-going
           # generates the actual website
           sphinx-build -b html docs docs/_build/html
         env:
diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml
new file mode 100644
index 0000000000..55e510c6ab
--- /dev/null
+++ b/.github/workflows/linkcheck.yml
@@ -0,0 +1,80 @@
+
+name: Documentation Link Checker
+
+on:
+  schedule:
+    # Run every Monday at 9:00 AM UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@eb1897b8dc4b5d5bfe39a428a8f2304605e0983c  # v7.0.0
+        with:
+          python-version: '3.12'
+          enable-cache: true
+
+      - name: Set venv
+        run: uv venv --python 3.12 $GITHUB_WORKSPACE/venv
+
+      - name: Install dependencies
+        run: . $GITHUB_WORKSPACE/venv/bin/activate && uv pip install -r src/dependencies/requirements/requirements_docs.txt
+
+      - name: Run Sphinx linkcheck
+        id: linkcheck
+        continue-on-error: true
+        run: |
+          . $GITHUB_WORKSPACE/venv/bin/activate
+          sphinx-build -b linkcheck docs docs/_build/linkcheck -q --keep-going
+          echo "exit_code=$?" >> $GITHUB_OUTPUT
+
+      - name: Prepare issue body
+        if: steps.linkcheck.outcome == 'failure'
+        run: |
+          DATE=$(date +%Y-%m-%d)
+          echo "ISSUE_DATE=$DATE" >> $GITHUB_ENV
+
+          cat > issue-body.md << 'EOF'
+          ## Documentation Link Check Failed
+
+          The weekly documentation link checker has detected broken links.
+
+          **Workflow Run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+
+          ### Broken Links Report
+
+          EOF
+
+          if [ -f docs/_build/linkcheck/output.txt ]; then
+            echo '```' >> issue-body.md
+            cat docs/_build/linkcheck/output.txt >> issue-body.md
+            echo '```' >> issue-body.md
+          else
+            echo 'No output file generated.' >> issue-body.md
+          fi
+
+          echo '' >> issue-body.md
+          echo 'Please review and fix the broken links in the documentation.' >> issue-body.md
+
+      - name: Create issue for broken links
+        if: steps.linkcheck.outcome == 'failure'
+        uses: peter-evans/create-issue-from-file@fca9117c27cdc29c6c4db3b86c48e4115a786710  # v6.0.0
+        with:
+          title: Documentation Link Check Failed - ${{ env.ISSUE_DATE }}
+          content-filepath: ./issue-body.md
+          labels: |
+            documentation