Hugo docs: Support reviews of Hugo updates by publishing to a clone's gh-pages

Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>

Author: bernhardkaindl

.github/workflows/hugo.yml

@@ -1,13 +1,22 @@
 name: Generate and upload Hugo docs
 
 on:
+  # Only run the workflow on changes to the following paths
   push:
     branches: master
+  pull_request:
+    paths:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
 
 jobs:
-  ocaml:
+  hugo:
     name: Docs
     runs-on: ubuntu-22.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    env:
+      DEP: ${{ vars.PREVIEW_HUGO_DOCS }}
 
     steps:
       - name: Checkout code
@@ -18,13 +27,19 @@ jobs:
         with:
           hugo-version: '0.127.0'
 
-      - name: Build
+      - name: Build with defaults from doc/hugo.yml for the xapi-project/xen-api master
+        if: |
+          github.repository == 'xapi-project/xen-api' &&
+          github.ref == 'refs/heads/master'
         run: |
           cd doc
           hugo --minify
 
-      - name: Deploy
+      - name: Deploy xapi-project/xen-api master to https://xapi-project.github.io/new-docs
         uses: peaceiris/actions-gh-pages@v4
+        if: |
+          github.repository == 'xapi-project/xen-api' &&
+          github.ref == 'refs/heads/master'
         with:
           deploy_key: ${{ secrets.ACTIONS_DOCS_DEPLOY_KEY }}
           publish_dir: ./doc/public
@@ -35,3 +50,41 @@ jobs:
           destination_dir: new-docs # temporary staging branch
           allow_empty_commit: false
           enable_jekyll: true # do not create .nojekyll file
+
+      - name: Build to deploy to a clone's GitHub Pages for documentation update reviews
+        if: ${{ vars.PREVIEW_HUGO_DOCS == 'true' || env.DEP == 'true' }}
+        env:
+          # Override the Hugo baseUrl in doc/hugo.toml with the repo name for doc reviews:
+          HUGO_BASEURL: ${{ steps.deployment.outputs.page_url }}
+        run: cd doc;hugo --minify
+
+
+  # When pushed to other repositories, deploy to the repository's GitHub Pages
+  preview-docs:
+    # Add a dependency to the hugo job, skip if the hugo job did not complete
+    needs: hugo
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      id-token: write  # Required for the deployment job to access the uploaded artifact
+      pages: write     # Required for the deployment job to deploy to GitHub Pages
+
+    # Deploy to the github-pages environment for doc reviews
+    # This variable is used in the preview-docs job to determine whether to preview the Hugo docs
+    # You can set this variable in the repository's environment or secrets settings:
+    if: vars.PREVIEW_HUGO_DOCS
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Upload Hugo static site as an artifact for documentation update reviews
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./doc/public
+
+      - name: Deploy uploaded artifact to GitHub Pages for documentation update reviews
+        id: deployment
+        uses: actions/deploy-pages@v4