feat(ci): add lychee broken link test

Signed-off-by: skjnldsv <skjnldsv@protonmail.com>

Author: skjnldsv

.github/workflows/sphinxbuild.yml

@@ -103,8 +103,20 @@ jobs:
       run: pip install -r requirements.txt
 
     - name: Build html documentation
+      env:
+        SPHINXOPTS: "-W --keep-going"
       run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }}
 
+    - name: Compute release version
+      id: release_version
+      run: |
+        branch="${GITHUB_REF#refs/heads/}"
+        if [[ "$branch" == stable* ]]; then
+          echo "release=${branch#stable}" >> $GITHUB_OUTPUT
+        else
+          echo "release=latest" >> $GITHUB_OUTPUT
+        fi
+
     - name: Compute PDF release version
       if: ${{ matrix.manual.build_pdf_path }}
       id: pdf_version
@@ -134,14 +146,17 @@ jobs:
         name: ${{ matrix.manual.name }}
         path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
 
-  deploy:
-    name: Deploy pages
+  # Assembles all artifacts into the gh-pages layout and uploads a single
+  # "staged" artifact that both `check` and `deploy` consume.  Doing the
+  # assembly once avoids repeating the checkout + merge logic in both jobs.
+  stage:
+    name: Stage documentation
     needs: build
     runs-on: ubuntu-latest
-    if: github.event_name == 'push'  # Only deploy on push, not PR
 
-    permissions:
-      contents: write
+    outputs:
+      branch_name: ${{ steps.branch.outputs.branch_name }}
+      version_name: ${{ steps.branch.outputs.version_name }}
 
     steps:
     - name: Cache git metadata
@@ -153,14 +168,14 @@ jobs:
           git-metadata-${{ github.sha }}
           git-metadata
 
-    - name: Checkout Github Pages branch
+    - name: Checkout gh-pages (for redirect sources)
       uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         ref: gh-pages
         fetch-depth: 0
         token: ${{ secrets.COMMAND_BOT_PAT }}
 
-    - name: Download all ${{ needs.build.outputs.branch_name }} artifacts
+    - name: Download all build artifacts
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
       with:
         path: artifacts/
@@ -170,44 +185,33 @@ jobs:
       run: |
         current_branch="${GITHUB_REF#refs/heads/}"
 
-        # Find the highest numbered stable branch from the remote
         highest_stable=$(git ls-remote --heads origin | sed -n 's?.*refs/heads/stable\([0-9]\{2\}\)$?\1?p' | sort -n | tail -1)
         highest_stable_branch="stable${highest_stable}"
 
         echo "Current branch: $current_branch"
         echo "Highest stable branch found: $highest_stable_branch"
 
-        # Map actual branch names to deployment folder names
         case "$current_branch" in
           "master")
             echo "branch_name=latest" >> $GITHUB_OUTPUT
             ;;
           "$highest_stable_branch")
             echo "branch_name=stable" >> $GITHUB_OUTPUT
-            # Also record the numeric version so we can publish to server/<number>/ too
             echo "version_name=${highest_stable}" >> $GITHUB_OUTPUT
             ;;
           *)
-            # Remove stable prefix for current branch
             current_branch="${current_branch#stable}"
             echo "branch_name=$current_branch" >> $GITHUB_OUTPUT
             ;;
         esac
 
-        echo "Deployment folder name: ${{ steps.branch.outputs.branch_name }}"
-        echo "Version name for additional deployment (if applicable): ${{ steps.branch.outputs.version_name }}"
-
-    - name: Merge ${{ steps.branch.outputs.branch_name }} documentation artifacts into gh-pages
+    - name: Merge artifacts into gh-pages layout
       run: |
-        # List artifacts
         ls -la artifacts/*/
 
-        # Cleanup old documentation
-        rm -rf ${{ steps.branch.outputs.branch_name }}
         rm -rf server/${{ steps.branch.outputs.branch_name }}
         mkdir -p server/${{ steps.branch.outputs.branch_name }}
 
-        # Copy all built documentation into dedicated subdirectories
         for artifact in artifacts/*; do
           if [ -d "$artifact" ]; then
             manual_name="$(basename "$artifact")"
@@ -216,48 +220,117 @@ jobs:
           fi
         done
 
-        # Move pdf files to the root of the branch_name
         mv server/${{ steps.branch.outputs.branch_name }}/*/*.pdf server/${{ steps.branch.outputs.branch_name }}/ || true
 
-        # If this is the highest stable branch, also deploy to its versioned folder
         if [ -n "${{ steps.branch.outputs.version_name }}" ]; then
-          rm -rf server/${{ steps.branch.outputs.version_name }}
           cp -r server/${{ steps.branch.outputs.branch_name }} server/${{ steps.branch.outputs.version_name }}
         fi
 
-        # Cleanup
         find . -type d -empty -delete
         rm -rf artifacts
 
     - name: Add various redirects for go.php and user_manual english version
       run: |
-        # Fetch source branches so git checkout origin/... works from the gh-pages checkout
         git fetch origin ${{ github.event.repository.default_branch }} ${{ github.ref_name }}
 
-        # Generate go.php redirect from main branch
         git checkout origin/${{ github.event.repository.default_branch }} -- go.php/index.html
         mkdir -p server/${{ steps.branch.outputs.branch_name }}/go.php
         mv go.php/index.html server/${{ steps.branch.outputs.branch_name }}/go.php/index.html
 
-        # Generate user_manual english redirect
         git checkout origin/${{ github.ref_name }} -- user_manual/index.html
         mkdir -p server/${{ steps.branch.outputs.branch_name }}/user_manual
         mv user_manual/index.html server/${{ steps.branch.outputs.branch_name }}/user_manual/index.html
 
-    - name: Commit ${{ steps.branch.outputs.branch_name }} documentation and push to gh-pages
+    - name: Upload staged site
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+      with:
+        name: staged-site
+        path: server/
+
+  check:
+    name: Check staged documentation
+    needs: stage
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Download staged site
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      with:
+        name: staged-site
+        path: server/
+
+    - name: Check for broken links with lychee
+      uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
+      with:
+        fail: true
+        token: ${{ secrets.GITHUB_TOKEN }}
+        jobSummary: true
+        args: |
+          --offline --no-progress --verbose
+          --remap "https://docs.nextcloud.com/server/${{ needs.stage.outputs.branch_name }} file://$(pwd)/server/${{ needs.stage.outputs.branch_name }}"
+          'server/${{ needs.stage.outputs.branch_name }}/**/*.html'
+
+
+  deploy:
+    name: Deploy documentation to gh-pages
+    needs: [stage, check]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+
+    permissions:
+      contents: write
+
+    steps:
+    - name: Cache git metadata
+      uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+      with:
+        path: .git
+        key: git-metadata-${{ github.sha }}
+        restore-keys: |
+          git-metadata-${{ github.sha }}
+          git-metadata
+
+    - name: Checkout gh-pages branch
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        ref: gh-pages
+        fetch-depth: 0
+        token: ${{ secrets.COMMAND_BOT_PAT }}
+
+    - name: Download staged site
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      with:
+        name: staged-site
+        path: incoming/
+
+    - name: Apply staged site to gh-pages working tree
+      run: |
+        branch="${{ needs.stage.outputs.branch_name }}"
+        version="${{ needs.stage.outputs.version_name }}"
+
+        rm -rf "server/${branch}"
+        cp -r "incoming/${branch}" "server/${branch}"
+
+        if [ -n "${version}" ]; then
+          rm -rf "server/${version}"
+          cp -r "incoming/${version}" "server/${version}"
+        fi
+
+        find . -type d -empty -delete
+
+    - name: Commit and push to gh-pages
       run: |
         git config --local user.email "nextcloud-command@users.noreply.github.com"
         git config --local user.name "nextcloud-command"
         git add .
-        git diff --staged --quiet || git commit -m "chore: deploy documentation for ${{ steps.branch.outputs.branch_name }}"
-        # Ensure we are up to date with the remote gh-pages branch
+        git diff --staged --quiet || git commit -m "chore: deploy documentation for ${{ needs.stage.outputs.branch_name }}"
         git pull --rebase origin gh-pages || true
         git push origin gh-pages || echo "Nothing to push (expected if no changes)"
       env:
         GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }}
 
   summary:
-    needs: build
+    needs: [build, check]
     runs-on: ubuntu-latest
     if: always()
 
@@ -267,6 +340,5 @@ jobs:
     name: build-deploy-summary
 
     steps:
-      # Only check if the build was successful
       - name: Summary status
-        run: if ${{ needs.build.result != 'success' }}; then exit 1; fi
+        run: if ${{ needs.build.result != 'success' || needs.check.result != 'success' }}; then exit 1; fi