From 26d305e26cb86913239fc28256d1092aa3d8a775 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

Also adds linkchecker and docs build to pypi_release action
---
 .github/workflows/check_docs_build.yml |  5 +-
 .github/workflows/linkcheck.yml        | 81 ++++++++++++++++++++++++++
 .github/workflows/pypi_release.yml     | 13 ++++-
 3 files changed, 95 insertions(+), 4 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..42618333b4 100644
--- a/.github/workflows/check_docs_build.yml
+++ b/.github/workflows/check_docs_build.yml
@@ -3,6 +3,7 @@ name: Check the Documentation Build
 on:
   pull_request:
     types: [opened, synchronize]
+  workflow_call:
   workflow_dispatch:
 
 permissions:
@@ -13,7 +14,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 +55,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..bc1e36b1c0
--- /dev/null
+++ b/.github/workflows/linkcheck.yml
@@ -0,0 +1,81 @@
+
+name: Documentation Link Checker
+
+on:
+  schedule:
+    # Run every Monday at 9:00 AM UTC
+    - cron: '0 9 * * 1'
+  workflow_call:
+  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
diff --git a/.github/workflows/pypi_release.yml b/.github/workflows/pypi_release.yml
index 495e682867..a90f70620a 100644
--- a/.github/workflows/pypi_release.yml
+++ b/.github/workflows/pypi_release.yml
@@ -42,7 +42,18 @@ jobs:
     needs: [release_approval]
     uses: ./.github/workflows/build_and_test_maxtext.yml
     secrets: inherit
-      
+
+  build_docs:
+    name: Build Documentation
+    needs: [build_and_test_maxtext_package]
+    uses: ./.github/workflows/check_docs_build.yml
+    secrets: inherit
+
+  check_links:
+    name: Check Links in Documentation
+    uses: ./.github/workflows/linkcheck.yml
+    secrets: inherit
+
   publish_maxtext_package_to_pypi:
     name: Publish MaxText package to PyPI
     needs: [build_and_test_maxtext_package]