perf(ci): optimize latex caching

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

Author: skjnldsv

.github/workflows/sphinxbuild.yml

@@ -34,6 +34,7 @@ jobs:
           restore-keys: |
             latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-
             latex-apt-${{ runner.os }}-${{ runner.arch }}-
+          lookup-only: true
 
       - name: Download LaTeX packages (cache miss only)
         if: steps.cache-latex-apt.outputs.cache-hit != 'true'
@@ -47,6 +48,13 @@ jobs:
           # Ensure downloaded packages are owned by the current user so they can be cached
           sudo chown -R $(id -u):$(id -g) ${{ runner.temp }}/.cache/archives
 
+      - name: Save LaTeX apt cache (cache miss only)
+        if: steps.cache-latex-apt.outputs.cache-hit != 'true'
+        uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: ${{ runner.temp }}/.cache/archives
+          key: latex-apt-${{ runner.os }}-${{ runner.arch }}-ubuntu-24.04-texlive-2023
+
   build:
     name: Build ${{ matrix.manual.name }}
     runs-on: ubuntu-latest
@@ -121,6 +129,7 @@ jobs:
 
       - name: Install LaTeX from cache
         if: ${{ matrix.manual.build_pdf_path }}
+        timeout-minutes: 3
         run: |
           sudo DEBIAN_FRONTEND=noninteractive apt-get update
           sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
@@ -317,7 +326,7 @@ jobs:
           branch="${{ steps.branch.outputs.branch_name }}"
 
           # Create the branch folder directly
-          mkdir -p "deploy-staging/${branch}"
+          mkdir -p "stage/${branch}"
 
           # Copy artifacts preserving their manual folder structure
           # Each artifact (user_manual, admin_manual, developer_manual) contains
@@ -326,20 +335,20 @@ jobs:
             if [ -d "$artifact" ]; then
               manual_name="$(basename "$artifact")"
               # Create the manual-specific folder
-              mkdir -p "deploy-staging/${branch}/${manual_name}"
+              mkdir -p "stage/${branch}/${manual_name}"
               # Copy artifact contents into the manual folder
-              cp -r "$artifact/"* "deploy-staging/${branch}/${manual_name}/"
+              cp -r "$artifact/"* "stage/${branch}/${manual_name}/"
             fi
           done
 
           # Move PDF files to the root of the branch folder for cleaner structure
-          find "deploy-staging/${branch}/" -maxdepth 2 -name "*.pdf" -type f -exec mv {} "deploy-staging/${branch}/" \;
+          find "stage/${branch}/" -maxdepth 2 -name "*.pdf" -type f -exec mv {} "stage/${branch}/" \;
 
           # Clean up empty directories
-          find deploy-staging -type d -empty -delete
+          find stage -type d -empty -delete
 
           echo "Staged artifacts for ${branch}:"
-          find deploy-staging -type f | head -20
+          find stage -type f | head -20
 
       # ========================================================================
       # CACHE STAGING ARTIFACTS
@@ -350,7 +359,7 @@ jobs:
       - name: Cache staged artifacts
         uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
         with:
-          path: deploy-staging/
+          path: stage/
           key: staged-docs-${{ github.sha }}
 
   # ============================================================================
@@ -446,20 +455,27 @@ jobs:
             echo "has_changes=true" >> $GITHUB_OUTPUT
           fi
 
+        # Remove the stage/ directory BEFORE creating the PR so it doesn't get committed
+      - name: Clean up staging cache before commit
+        run: rm -rf stage/
+
       - name: Create Pull Request for documentation deployment
         uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
         id: cpr
         if: steps.apply.outputs.has_changes == 'true'
         with:
           token: ${{ secrets.COMMAND_BOT_PAT }}
-          commit-message: "chore: update documentation for ${{ needs.stage-and-check.outputs.branch_name }}"
+          commit-message: "chore: update documentation for `${{ needs.stage-and-check.outputs.branch_name }}`"
           committer: nextcloud-command <nextcloud-command@users.noreply.github.com>
           author: nextcloud-command <nextcloud-command@users.noreply.github.com>
           signoff: true
           branch: "automated/deploy/documentation-${{ needs.stage-and-check.outputs.branch_name }}"
           base: gh-pages
-          title: "Documentation update for ${{ needs.stage-and-check.outputs.branch_name }}"
-          body: "Automated documentation update from branch ${{ github.ref_name }}"
+          title: "Documentation update for `${{ needs.stage-and-check.outputs.branch_name }}`"
+          body: |
+            This PR was automatically generated by the CI workflow and
+            includes the latest changes for the `${{ needs.stage-and-check.outputs.branch_name }}` branch.
+
           delete-branch: true
           labels: "automated, 3. to review"
 
@@ -481,4 +497,13 @@ jobs:
 
     steps:
       - name: Summary status
-        run: if ${{ needs.build.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'success' }}; then exit 1; fi
+        run: |
+          if ${{ github.event_name == 'pull_request' }}
+          then
+            echo "This workflow ran for a pull request. We need build and stage-and-check to succeed, but deploy will be skipped"
+            if ${{ needs.build.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'skipped' }}; then exit 1; fi
+          else
+            echo "This workflow ran for a push. We need all jobs to succeed, including deploy"
+            if ${{ needs.build.result != 'success' || needs.stage-and-check.result != 'success' || needs.deploy.result != 'success' }}; then exit 1; fi
+          fi
+