Docs add possibility to preview in clone

.github/workflows/hugo.yml

@@ -3,11 +3,21 @@ name: Generate and upload Hugo docs
 on:
   push:
     branches: master
+  pull_request:
+    # Only run the workflow on changes to the following paths
+    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,52 @@ jobs:
           destination_dir: new-docs # temporary staging branch
           allow_empty_commit: false
           enable_jekyll: true # do not create .nojekyll file
+
+      # Deploy to the github-pages environment for doc reviews in other repositories
+      # if vars.PREVIEW_HUGO_DOCS set by the admin in the repository's environment
+      # This is done without commiting to the repository's gh-pages branch, only
+      # an artifact is deployed to the clone's github-pages environment instead:
+
+      - 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:
+          # Override the Hugo baseUrl in doc/hugo.toml with the repo name for doc reviews:
+          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
+
+    # 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 }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - name: Deploy uploaded artifact to GitHub Pages for documentation update reviews
+        if: ${{ needs.hugo.outputs.preview == 'true' }}
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -1,8 +1,15 @@
 name: Build and test
 
 on:
+  # Skip if only doc changes are made on pushes and pull_requests
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/**'
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/**'
   schedule:
     # run daily, this refreshes the cache
     - cron: "13 2 * * *"

.github/workflows/other.yml

@@ -1,8 +1,15 @@
 name: Build and test (other)
 
 on:
+  # Skip if only doc changes are made on pushes and pull_requests
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/**'
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/**'
   schedule:
     # run daily, this refreshes the cache
     - cron: "13 2 * * *"

.github/workflows/shellcheck.yaml

@@ -2,6 +2,9 @@ name: ShellCheck
 
 on:
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/**'
   merge_group:
 
 concurrency:  # On new push, cancel old workflows from the same PR, branch or tag:

doc/README.md

@@ -1,9 +1,51 @@
-Quick start guide:
+# Quick start guide:
 
 - Visit https://xapi-project.github.io/new-docs/ to view the current documentation.
+
+## Required software
+
+The docs use Hugo and the [Hugo Relearn theme](https://mcshelby.github.io/hugo-theme-relearn),
+an enhanced fork of the popular Hugo Learn theme.
+
+### Compatible versions
+
+Due to a number of gradual changes in Hugo and Relearn,
+the docs are currently only compatible with specific older versions of Hugo and Relearn.
+
+Hugo v0.121.0 to ~v0.127.0 (the current version of the Ubuntu `snap` is too recent)
+- Fixes to support newer versions are forthcoming.
+
+Hugo Relearn 5.24.0 (defined by a git tag in doc/go.mod)
+- Note: Hugo Relearn >= 5.25 currently trigger additional warnings due to deprecations.
+- Further updates fix this situation are forthcoming step by step.
+
+Hugo Relearn >= 5.24.0 and < 6.x are expected to work:
+- https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/5/index.html#5-24-0
+- Breaking changes in Relearn 6.0.0:
+  https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/6/#6-0-0
+
+## Installation
+
 - Install Hugo; follow the guidance on https://gohugo.io/getting-started/installing.
-  You'll need Go as well: see https://go.dev/
-  - On Ubuntu 22.04 and older, use `sudo snap install hugo` to get the needed newer version of `hugo`.
+  You'll need to install Go as well: see https://go.dev/
+  - Hugo installation is described at https://gohugo.io/installation
+  - On Ubuntu 24.04, the version installed by `apt` works.
+  - On Ubuntu 22.04 and older:
+    - `apt-get install hugo` would install a version that is too old.
+    - `sudo snap install hugo` installs a too recent version
+
+  - To install Hugo from source, you need a recent `golang-1.2x` compiler:
+    - On Ubuntu 22.04, this can be done with:
+      ```bash
+      sudo apt install golang-1.23-go
+      # Add it to your path, assuming your .local/bin/ is early in your PATH:
+      ln -s /usr/lib/go-1.23/bin/go ~/.local/bin/go
+      go version
+      go install github.com/gohugoio/hugo@v0.127.0
+      ```
+
+## Development
+
 - Run a local server: `hugo server`
 - Open a browser at http://127.0.0.1:1313/new-docs/
 - Add content to `doc/content/`:

doc/content/design/cpu-levelling-v2.md

@@ -29,7 +29,7 @@ The old XS 5.6-style Heterogeneous Pool feature that is based around hardware-le
 History
 =======
 
-- Original XS 5.6 design: [heterogeneous-pools](../heterogeneous-pools)
+- Original XS 5.6 design: [heterogeneous-pools](heterogeneous-pools)
 - Changes made in XS 5.6 FP1 for the DR feature (added CPUID checks upon migration)
 - XS 6.1: migration checks extended for cross-pool scenario
 

doc/content/design/local-database.md

@@ -25,7 +25,7 @@ We propose to:
   this should reduce the number of RPCs across the network.
 
 In a later phase we can move to a completely
-[distributed database](../distributed-database).
+[distributed database](distributed-database/index).
 
 Replicating the database
 ------------------------

doc/content/design/multiple-cluster-managers.md

@@ -14,7 +14,7 @@ revision_history:
 Introduction
 ------------
 
-Xapi currently uses a cluster manager called [xhad](../../features/HA/HA.html). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
+Xapi currently uses a cluster manager called [xhad](../toolstack/features/HA/index). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
 
 1. modify the other software to take membership information from xapi; or
 2. modify xapi to take membership information from this other software.
@@ -70,4 +70,4 @@ The `xapi.conf` file will have a new field: `cluster-stack-root` which will have
 
 In `Pool.enable_ha` with `cluster_stack="foo"` we will verify that the subdirectory `<cluster-stack-root>/foo` exists. If it does not exist, then the call will fail with `UNKNOWN_CLUSTER_STACK`.
 
-Alternative cluster stacks will need to conform to the exact same interface as [xhad](../../features/HA/HA.html).
+Alternative cluster stacks will need to conform to the exact same interface as [xhad](../toolstack/features/HA).

doc/content/design/ocfs2/index.md

@@ -461,7 +461,7 @@ Summary of the impact on the admin
 
 OCFS2 is fundamentally a different type of storage to all existing storage
 types supported by xapi. OCFS2 relies upon O2CB, which provides
-[Host-level High Availability](../../../features/HA/HA.html). All HA implementations
+[Host-level High Availability](../../toolstack/features/HA/index). All HA implementations
 (including O2CB and `xhad`) impose restrictions on the server admin to
 prevent unnecessary host "fencing" (i.e. crashing). Once we have OCFS2 as
 a feature, we will have to live with these restrictions which previously only

doc/content/xapi/cli/_index.md

@@ -179,5 +179,5 @@ Yet other commands do not actually do any XenAPI calls, but instead get "helpful
 
 The following tutorials show how to extend the CLI (and XenAPI):
 
--   [Adding a field]({{< relref "../guides/howtos/add-field.md" >}})
--   [Adding an operation]({{< relref "../guides/howtos/add-function.md" >}})
+-   [Adding a field](../guides/howtos/add-field)
+-   [Adding a function](../guides/howtos/add-function)

doc/content/xapi/guides/howtos/add-class.md

@@ -6,8 +6,8 @@ This document describes how to add a new class to the data model that
 defines the Xen Server API. It complements two other documents that
 describe how to extend an existing class:
 
-* [Adding a Field]({{< ref add-field.md >}})
-* [Adding a Function]({{< ref add-function.md >}})
+* [Adding a field](add-field)
+* [Adding a function](add-function)
 
 As a running example, we will use the addition of a class that is part
 of the design for the PVS Direct feature. PVS Direct introduces

doc/content/xen-api/topics/snapshots.md

@@ -11,7 +11,7 @@ They can be used for:
 - experiments (take snapshot, try something, revert back again)
 - golden images (install OS, get it just right, clone it 1000s of times)
 
-Read more about [Snapshots: the High-Level Feature](../features/snapshots/snapshots.html).
+Read more about [Snapshots: the High-Level Feature](../../toolstack/features/snapshots/index).
 
 Taking a VDI snapshot
 =====================

doc/go.mod

@@ -2,4 +2,4 @@ module xapi-project.github.io
 
 go 1.20
 
-require github.com/McShelby/hugo-theme-relearn v0.0.0-20230905210935-196188b7f3bd // indirect
+require github.com/McShelby/hugo-theme-relearn v0.0.0-20231029175538-7ae1435626d7 // indirect