Add PR Preview Deployments for Documentation

[mgajek-cern]

Context

We build documentation on every PR to catch issues before merge. However, these build artifacts are currently discarded - only main branch builds get deployed.

This is especially problematic for external contributors who cannot easily run the full documentation build locally (requires Docker, rucio/rucio clone, API generation, etc.). Reviewers and contributors currently cannot see how their changes will look when rendered.

Proposal

Reuse PR build artifacts to create preview environments, allowing anyone (especially external contributors without local setup) to see rendered documentation changes.

Potential Solutions

Option 1: GitHub Pages PR Previews (Free, native)

- uses: rossjrw/pr-preview-action@v1
  with:
    source-dir: website/build

Preview URL: https://rucio.github.io/documentation/pr-preview/pr-123/

Option 2: Netlify Deploy Previews (Free tier, popular in OSS)

• Automatic preview URLs per PR
• Comments preview link on PR automatically
• Works for forks (external contributors)

Option 3: Surge.sh (Simple, free)

• Quick setup, ephemeral deployments
• URL: rucio-docs-pr-123.surge.sh

Option 4: GitHub Pages PR Previews (Free, native)

• Uses JamesIves/github-pages-deploy-action directly for cross-repo deployment
• Uses pull_request_target to support fork PRs with secrets access
• Deploys to gh-pages branch under pr-preview/pr-{number}/
• Automatic cleanup when PRs close
• Sticky PR comments with preview URLs
• Scheduled cleanup for orphaned previews

Preview URL: https://rucio.github.io/documentation/pr-preview/pr-123/

Benefits

• 🌍 External contributors can preview their changes without complex local setup
• 📖 Reviewers can see rendered changes instantly
• 🐛 Catch rendering/styling issues before merge
• ⚡ No extra build cost (already building on PRs)
• 🔗 Shareable preview links for feedback