Update 3

.github/workflows/_build_docs.yaml

@@ -0,0 +1,114 @@
+name: Build Documentation
+
+on:
+  workflow_call:
+    inputs:
+      base-url:
+        description: 'Base URL for Docusaurus'
+        required: false
+        type: string
+        default: '/documentation'
+      pr-ref:
+        description: 'Git ref to checkout (for PR previews)'
+        required: false
+        type: string
+        default: ''
+    outputs:
+      artifact-name:
+        description: "Name of the uploaded build artifact"
+        value: ${{ jobs.build.outputs.artifact-name }}
+
+jobs:
+  check_markdown_syntax:
+    name: Check Markdown Syntax
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.pr-ref || github.ref }}
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+      - run: gem install mdl
+      - run: ./tools/check-docs.sh
+
+  check_file_names:
+    name: Check File Names
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.pr-ref || github.ref }}
+      - run: ./tools/check-file-names.sh
+
+  check_shell_scripts:
+    name: Check Shell Scripts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.pr-ref || github.ref }}
+      - run: sudo apt-get install --yes shellcheck
+      - run: shellcheck **/*.sh
+
+  check_python_scripts:
+    name: Check Python Scripts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.pr-ref || github.ref }}
+      - run: pip install -r tools/requirements.txt
+      - run: black --check .
+      - run: isort --profile black --filter-files --check .
+      - run: flake8 --config tools/.flake8
+      - run: mypy --ignore-missing-imports .
+
+  build:
+    name: Build
+    outputs:
+      artifact-name: documentation-artifacts
+    needs: [check_markdown_syntax, check_file_names, check_shell_scripts, check_python_scripts]
+    runs-on: ubuntu-latest
+    permissions:
+      packages: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.pr-ref || github.ref }}
+
+      - uses: actions/checkout@v6
+        with:
+          repository: rucio/rucio
+          ref: master
+          path: tools/run_in_docker/rucio
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Install dependencies and build API docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python3 -m pip install -U pip setuptools
+          python3 -m pip install -U -r tools/requirements.txt
+          docker login https://docker.pkg.github.com -u ${{ github.actor }} -p ${{ secrets.GITHUB_TOKEN }}
+          ./tools/build_documentation.sh
+          docker logout https://docker.pkg.github.com
+
+      - name: Build Docusaurus site
+        working-directory: website
+        run: |
+          yarn install
+          yarn build
+        env:
+          BASE_URL: ${{ inputs.base-url }}
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-artifacts
+          path: website/build
+          retention-days: 7

.github/workflows/deploy_pr_preview.yaml

@@ -0,0 +1,154 @@
+name: Deploy PR Preview
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, closed]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event.action != 'closed'
+    uses: ./.github/workflows/_build_docs.yaml
+    secrets: inherit
+    permissions:  
+      packages: read
+    with:
+      base-url: ${{ github.event_name == 'pull_request_target' && format('/documentation/pr-preview/pr-{0}', github.event.pull_request.number) || '/documentation' }}
+      pr-ref: ${{ github.event.pull_request.head.sha }} 
+
+  deploy-preview:
+    name: Deploy Preview
+    needs: build
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          token: ${{ secrets.PREVIEW_TOKEN }}
+          persist-credentials: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: ${{ needs.build.outputs.artifact-name }}
+          path: website/build
+
+      - uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: website/build
+          repository-name: ${{ github.repository }}
+          branch: gh-pages
+          target-folder: pr-preview/pr-${{ github.event.pull_request.number }}
+          token: ${{ secrets.PREVIEW_TOKEN }}
+          clean: false
+          force: false
+
+      - name: Comment on PR
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PREVIEW_TOKEN }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const previewUrl = `https://${context.repo.owner}.github.io/${context.repo.repo}/pr-preview/pr-${prNumber}/`;
+
+            const comment = `## 🚀 Preview Deployed
+
+            Preview URL: ${previewUrl}
+
+            Built from commit: ${context.payload.pull_request.head.sha.substring(0, 7)}`;
+
+            // Find existing comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber
+            });
+
+            const botComment = comments.find(comment => 
+              comment.user.type === 'Bot' && 
+              comment.body.includes('Preview Deployed')
+            );
+
+            // Update or create comment
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: comment
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: comment
+              });
+            }
+
+  cleanup-preview:
+    name: Cleanup Preview
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          repository: ${{ github.repository }}
+          ref: gh-pages
+          token: ${{ secrets.PREVIEW_TOKEN }}
+
+      - name: Remove preview directory
+        run: |
+          rm -rf pr-preview/pr-${{ github.event.pull_request.number }}
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "Remove preview for PR #${{ github.event.pull_request.number }}" || echo "No changes to commit"
+          git push
+
+      - name: Comment on PR
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PREVIEW_TOKEN }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+
+            const comment = `## 🧹 Preview Removed
+
+            Preview has been removed because the PR was closed.`;
+
+            // Find existing comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber
+            });
+
+            const botComment = comments.find(comment => 
+              comment.user.type === 'Bot' && 
+              comment.body.includes('Preview')
+            );
+
+            // Update existing comment
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: comment
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: comment
+              });
+            }

.github/workflows/update_documentation.yml

@@ -1,110 +1,27 @@
 name: Update Documentation
+
 on:
   push:
-  pull_request:
+    branches: [main]
   schedule:
     - cron: '0 4 * * 1-5'
 
 jobs:
-  check_markdown_syntax:
-    name: Check Markdown Syntax
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-      - uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.4
-      - name: Install markdownlint
-        run: |
-          gem install mdl
-      - name: Lint docs
-        run: |
-          ./tools/check-docs.sh
-  check_file_names:
-    name: Check File Names
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-      - name: Check file names
-        run: |
-          ./tools/check-file-names.sh
-  check_shell_scripts:
-    name: Check Shell Scripts
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-      - name: Install dependencies
-        run: |
-          sudo apt-get install --yes shellcheck
-      - name: Check Shell Scripts
-        run: |
-          shellcheck **/*.sh
-  check_python_scripts:
-    name: Check Python Scripts
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-      - name: Install dependencies
-        run: |
-          pip install -r tools/requirements.txt
-      - name: Run black
-        run: |
-          black --check .
-      - name: Run isort
-        run: |
-          isort --profile black --filter-files --check .
-      - name: Run flake8
-        run: |
-          flake8 --config tools/.flake8
-      - name: MyPy
-        run: |
-          mypy --ignore-missing-imports .
   build:
-    name: Build
-    needs: [check_markdown_syntax, check_file_names, check_shell_scripts, check_python_scripts]
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/checkout@v6
-        with:
-          repository: rucio/rucio
-          ref: master
-          path: tools/run_in_docker/rucio
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 24
-      - name: Install rucio-api generation dependencies and build markdown sites for the API
-        run: |
-          python3 -m pip install -U pip setuptools
-          python3 -m pip install -U -r tools/requirements.txt
-          docker login https://docker.pkg.github.com -u ${{ github.actor }} -p ${{ secrets.GITHUB_TOKEN }}
-          ./tools/build_documentation.sh
-          docker logout https://docker.pkg.github.com
-      - name: Install dependencies and static website
-        run: |
-          cd website
-          yarn install
-          yarn build
-      - uses: actions/upload-artifact@master
-        with:
-          name: documentation-artifacts
-          path: website/build
+    uses: ./.github/workflows/_build_docs.yaml
+    secrets: inherit
+
   deploy:
     name: Deploy
     needs: build
-    if: github.ref == 'refs/heads/main' || github.event_name == 'schedule'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/download-artifact@master
+      - uses: actions/download-artifact@v4
         with:
-          name: documentation-artifacts
+          name: ${{ needs.build.outputs.artifact-name }}
           path: website/build
-      - name: Push to Github Pages branch
+      - name: Push to Github Pages
+        run: ./publish.sh
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: ./publish.sh