Hugo docs: When enabled by the fork, preview Hugo docs as its gh-pages

Signed-off-by: Bernhard Kaindl <[email protected]>

.github/workflows/hugo.yml

@@ -3,11 +3,21 @@ name: Generate and upload Hugo docs
 on:
   push:
     branches: master
+  pull_request:
+    # On pull requests, only run the workflow if Hugo docs are modified
+    paths:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
 
 jobs:
-  ocaml:
+  hugo:
     name: Docs
     runs-on: ubuntu-22.04
+    environment:
+      # To be able read var.PREVIEW_HUGO_DOCS, if set in the github-pages environment:
+      name: github-pages
+    outputs:
+      preview: ${{ steps.preview.outputs.done }}  # Set to true if the preview job runs
 
     steps:
       - name: Checkout code
@@ -25,6 +35,9 @@ jobs:
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4
+        # The deploy key used for deployment to https://xenapi-project.github.io
+        # It is stored in the repository's secrets and is used to push the built
+        # documentation. This step skips deployment if it is not set on a clone.
         with:
           deploy_key: ${{ secrets.ACTIONS_DOCS_DEPLOY_KEY }}
           publish_dir: ./doc/public
@@ -35,3 +48,66 @@ jobs:
           destination_dir: new-docs # temporary staging branch
           allow_empty_commit: false
           enable_jekyll: true # do not create .nojekyll file
+
+      # To optionally deploy Hugo docs for preview in forks, owners of forks can set
+      # change the deployment source of the fork to "GitHub Pages" at
+      # https://github.com/<user|organisation>/<repo>/settings/pages and set
+      # the variable PREVIEW_HUGO_DOCS to true in theo repository's environment at
+      # https://github.com/<user|organisation>/<repo>/settings/variables/actions
+      # On https://github.com/<user|organisation>/<repo>/settings/environments/
+      # the environment 'github-pages' must exist and in it, at "Deployment branches and tags"
+      # a rule allowing deploy from the PR branches must be added or this rule must be set to
+      # to "No restriction" to allow deployment from any branch in the fork. When all is set,
+      # this enables the github-pages site, renders the Hugo site for it, and uploads
+      # the renders site. This works using an artifact and does not commit to any branch.
+
+      - name: If vars.PREVIEW_HUGO_DOCS is true, enable github pages for the preview
+        if: ${{ vars.PREVIEW_HUGO_DOCS == 'true' }}  # Only runs if set by the admin
+        id: configure-pages
+        with:
+          enablement: true  # Enables GitHub Pages for the clone repository
+        uses: actions/configure-pages@v5  # output: the base_url for the preview site
+
+      - name: If vars.PREVIEW_HUGO_DOCS is true, build the hugo preview
+        if: ${{ vars.PREVIEW_HUGO_DOCS == 'true' }}
+        id: preview
+        env:
+          # Force Hugo to render the site using the baseUrl used by GitHub Pages for the preview:
+          # The default base URL used by GitHub pages of a repository is
+          # https://<user|organisation>.github.io/<repo name>
+          # Owners of forks can setup custom domains for the gh-pages of their repositories instead:
+          # https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site
+          # In this case, the base URL is the custom domain and we read it
+          # from the output of the output variable 'base_url' of the configure-pages action:
+          HUGO_BASEURL: ${{ steps.configure-pages.outputs.base_url }}
+        run: cd doc && hugo --minify && echo done=true >$GITHUB_OUTPUT
+
+      - name: If vars.PREVIEW_HUGO_DOCS is true, upload the Hugo site as an artifact
+        if: ${{ vars.PREVIEW_HUGO_DOCS == 'true' }}
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./doc/public
+
+
+  # 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
+
+    if: ${{ needs.hugo.outputs.preview == 'true' }}
+
+    # 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
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-24.04-arm
+    steps:
+      # If deployed, the summary of this step in the Workflow summary shows the site URL:
+      - name: Deploy uploaded artifact to GitHub Pages for documentation update reviews
+        id: deployment
+        uses: actions/deploy-pages@v4