docs: Update doc/README.md and Hugo Relearn (to 5.23.0 for now)

Minor updates of the Hugo documentation:

- The current Ubuntu snap package of Hugo is not supported by the docs.
  We should take a first minor step towards fixing this.

- `doc/README.md` is outdated and should be updated.
  It says that the Ubuntu snap of Hugo works, but it does not anymore.
  Fix this by updating the outdated information.

- An initial fix is to update the Relearn theme from 5.20.x to 5.23.0:
  - It does not introduce breaking changes.
  - It introduces more straightforward page links and deprecates older syntax.
  - Fix the warnings by updating relative links accordingly.

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

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/[email protected]
+      ```
+
+## 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/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/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