fix(ci): deploy pages via pull request with auto-merge

[skjnldsv]

fix(ci): deploy pages via pull request with auto-merge

Summary

Refactored the documentation CI workflow to improve performance, reduce costs, add link validation, and deploy via PR instead of direct pushes.

Changes

Performance: Shared LaTeX Cache

• Created a dedicated setup-latex-cache job that builds once and shares with all workers
• Saves time by avoiding redundant LaTeX package downloads

Cost Reduction

• Instead of uploading ~1.8GB of artifacts, we cache the staged build and pass it between jobs
• Faster CI

New stage-and-check Job

• Determines deployment targets (master → latest, stable32 → stable + 32, etc.)
• Organizes artifacts into clean staging structure
• Passes to deploy job via cache
• Future tasks
  • Validates all links with lychee before deployment

Safer Deployment via PR

• Deployment now creates a PR to gh-pages instead of direct push
• Auto-merges if validation passes
• Provides audit trail and prevents direct branch modifications

Concurrency Control

• Added concurrency group to cancel duplicate builds on rapid commits

Branch Mapping

• master → server/latest/
• stable<N> (highest) → server/stable/ + server/<N>/
• stable<N> (older) → server/<N>/ only

Result

• Faster builds (shared cache)
• Better validation before deploy
• More controlled and traceable process