docs: preview in PRs

.github/actions/deploy-versioned-pages/action.yml

@@ -0,0 +1,79 @@
+# *******************************************************************************
+# Copyright (c) 2024 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+name: Deploy Versioned Pages
+description: Will push the documentation to the gh-pages branch, possibly with a versioned URL. When the PR is closed, the documentation will be deleted.
+# Note: this has some shortcomings, like race conditions when multiple PRs are opened at the same time,
+# problems with overwriting existing files, not deleting deleted files, etc.
+# We'll address these when we transform this action into a truly reusable independent action.
+# But for now, let's get it working!
+inputs:
+  source_folder:
+    description: "Path to the html files to deploy in current working directory"
+    required: true
+  versions_file:
+    description: "Path to the versions file on gh-pages branch"
+    default: "versions"
+  create_comment:
+    description: "Create a comment on the PR with the URL to the documentation" # in case of PR
+    default: "true"
+outputs:
+  target_folder:
+    description: "The target folder for the documentation"
+    value: ${{ steps.calc.outputs.target_folder }}
+runs:
+  using: "composite"
+  steps:
+    - name: Determine target_folder
+      id: calc
+      shell: bash
+      run: |
+        if [[ ${{github.event_name}} == 'pull_request' ]]; then
+          echo "target_folder=pr-${{github.event.pull_request.number}}" >> $GITHUB_OUTPUT
+        elif [[ ${{github.ref_name}} != 'main' ]]; then
+          echo "target_folder=${{github.ref_name}}" >> $GITHUB_OUTPUT
+        else
+          echo "target_folder=/" >> $GITHUB_OUTPUT
+        fi
+    - name: Prepare
+      shell: bash
+      run: |
+        # Prepare the deploy folder
+        mkdir -p deploy_root/${{ steps.calc.outputs.target_folder }}
+        # Move the files to the deploy folder
+        mv ${{ inputs.source_folder }}/* deploy_root/${{ steps.calc.outputs.target_folder }}
+        # Ensure that the folder is not treated as a Jekyll site
+        touch deploy_root/.nojekyll
+
+        # Add the target folder to the versions file
+        git fetch origin gh-pages --depth 1
+        git checkout origin/gh-pages -- "${{ inputs.versions_file }}"
+        if ! grep -qx "${{ steps.calc.outputs.target_folder }}" "${{ inputs.versions_file }}"; then
+          echo "${{ steps.calc.outputs.target_folder }}" >> "${{ inputs.versions_file }}"
+        fi
+        mv "${{ inputs.versions_file }}" deploy_root/
+        ls -al .
+        ls -al deploy_root
+    - name: Deploy 🚀
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        folder: deploy_root
+        clean: false
+    - name: Comment on PR with docs URL
+      if: ${{ github.event_name == 'pull_request' && inputs.create_comment == 'true' }}
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        issue-number: ${{github.event.pull_request.number}}
+        body: |
+          The created documentation from the pull request is available at: [docu-html](https://eclipse-score.github.io/score/${{steps.calc.outputs.target_folder}})
+        reactions: rocket

.github/workflows/docs-cleanup.yml

@@ -0,0 +1,50 @@
+# *******************************************************************************
+# Copyright (c) 2024 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+name: Cleanup Documentation
+on:
+  pull_request:
+    types: [closed]
+  delete:
+jobs:
+  docs-build-cleanup:
+    name: Remove build documentation
+    # Remove the corresponding documentation from the gh-pages branch,
+    # after a PR is closed or a branch is deleted.
+    runs-on: ubuntu-latest
+    concurrency:
+      group: gh-pages
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Remove version
+        run: |
+          if [[ ${{ github.event_name }} == "pull_request" ]]; then
+            VERSION="pr-${{ github.event.pull_request.number }}"
+          else
+            VERSION="${{ github.ref_name }}"
+          fi
+
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+          # Delete the folder and remove the version from the versions file
+          rm -rf "${VERSION}"
+          sed -i "/^$VERSION$/d" versions
+      - name: Push changes to gh-pages branch
+        uses: EndBug/add-and-commit@v9
+        with:
+          message: "Cleanup ${{ env.VERSION }}"
+          add: .
+          new_branch: "gh-pages"

.github/workflows/docs.yml

@@ -11,7 +11,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
 
-name: Documentation build
+name: Documentation
 on:
   pull_request:
     types: [opened, reopened, synchronize]
@@ -22,6 +22,11 @@ on:
     types: [checks_requested]
 jobs:
   docs-build:
+    name: Build documentation
+    # Build the documentation and upload it as an artifact
+
+    # TBD: maybe it's easier to separate `closed` into a separate workflow?
+    if: ${{ (github.event_name != 'pull_request' || github.event.action != 'closed') }}
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
@@ -33,41 +38,42 @@ jobs:
       - name: Build documentation
         run: |
           bazel build //docs:github-pages && cp bazel-bin/docs/github-pages.tar .
-      - name: Upload artifact for deployment
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: actions/[email protected]
-        with:
-          name: github-pages
-          path: ${{ github.workspace }}/github-pages.tar
-          retention-days: 1
-          if-no-files-found: error
-      - name: Upload artifact for pull request link
+      - name: Upload artifact for job analysis
         if: github.event_name == 'pull_request'
-        id: upload-artifact-pr
         uses: actions/[email protected]
         with:
           name: github-pages-${{ github.sha }}
-          path: ${{ github.workspace }}/github-pages.tar
+          path: github-pages.tar
           retention-days: 1
           if-no-files-found: error
-      - name: Comment artifact URL
-        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
-        run: |
-          gh pr comment ${{ github.event.pull_request.number }} \
-            --body "Documentation artifact: ${{ steps.upload-artifact-pr.outputs.artifact-url }}"
-        env:
-          GH_TOKEN: ${{ github.token }}
   docs-deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+    name: Deploy documentation to GitHub Pages
     permissions:
       pages: write
       id-token: write
+      contents: write
+    concurrency:
+      group: gh-pages
+      cancel-in-progress: false
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: docs-build
     steps:
-      - name: Deploy to GitHub Pages
+      - name: Download documentation artifact
+        uses: actions/[email protected]
+        with:
+          name: github-pages-${{ github.sha }}
+      - name: Untar documentation artifact
+        run: tar -xf github-pages.tar
+        # FIXME: query repository settings instead of blindly trying!
+      - name: Deploy 🚀
+        id: pages-deployment
+        continue-on-error: true
+        uses: ./.github/actions/deploy-versioned-pages
+        with:
+          source_folder: "."
+      - name: Deploy (fallback) 🚀
         id: deployment
+        # If the new deployment from gh-pages branch fails, at least deploy the current version.
+        # This is only a short-term solution, until we can change the repository settings.
+        if: ${{ steps.pages-deployment.outcome == 'failure' && github.event_name == 'push' && github.ref_name == 'main' }}
         uses: actions/[email protected]