Docs update to upstream hugo relearn 7.3.2 (#6267)

Minor fixup: It should be ready for a new round reviews now:

The incremental change consists only of the required incremental fixes
(see the [Compare
link](https://github.com/xapi-project/xen-api/compare/e92341cd8439a083e4c8ad54c55690de6f2c04a5..7f64d072899e05f39afe9fd3391bf00ddec2a099)
of it.

- Review comment from Pau applied: Reverted not running the required
pull_request workflows.
- Review comment from Pau applied: Fixed not even temporarily using
private forks: Squashed commits
  - While squashing those changes, I:
- Split change from `menuTitle` to `linkTitle` into an initial commit
(can be done first)
    - Squashed the changes for `doc/hugo.toml` into one commit.
- and extracted the change to `hugo.toml` into one commit (support
current Hugo versions)
- Squashed the changes for `doc/README.md` into one commit (no
intermediate changes)
- I found one inadvertent revert of a previous simplification: I removed
this accidental revert.

----
Hugo docs: Fix upstream Hugo compatibility:
- Includes the fixed commit from #6264, and
- Adds a 2nd commit to complete the fix for upstream compatibility.

### Update Hugo version support to work with the current Hugo version

This PR fixes using the Ubuntu snap to render the Hugo docs.

Relearn 7.x completely REMOVED the `header.html` and `footer.html`
partials
Partials that useed them are:
-
https://github.com/xapi-project/xen-api/blob/master/doc/layouts/xenapi/class.html
-
https://github.com/xapi-project/xen-api/blob/master/doc/layouts/xenapi/release.html
To update to 7.x, these had to be moved to the content.html partial, as
documented.

Changes:
- Hugo Relearn 6.x uses the `linkTitle` front matter option now:
Quote from the release notes: _The front matter option `menuTitle`
[deprecated in
5.24.0](https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/5/index.html#5-24-0)
was removed in favour for Hugo’s linkTitle._
- Newer versions of Hugo require the option `unsafe = true` to include
raw HTML.
- Two Hugo Relearn 6.x partials need fixes for newer versions of Hugo.

### Update doc/README.md accordingly

- Update the information on supported versions.
- Add information on the breaking changes in Hugo Relearn 7.x.x to watch
out for.
- While at it, fix/improve the formatting of doc/README.md:
  - Spelling fixes/improvements
  - Fix markdown linting errors (empty lines for spacing, no bare links)
      - Tidy up the document structure

Author: robhoes

.github/workflows/main.yml

@@ -7,9 +7,6 @@ on:
       - 'doc/**'
       - '.github/workflows/hugo.yml'
   pull_request:
-    paths-ignore:
-      - 'doc/**'
-      - '.github/workflows/hugo.yml'
   schedule:
     # run daily, this refreshes the cache
     - cron: "13 2 * * *"

.github/workflows/other.yml

@@ -7,9 +7,6 @@ on:
       - 'doc/**'
       - '.github/workflows/hugo.yml'
   pull_request:
-    paths-ignore:
-      - 'doc/**'
-      - '.github/workflows/hugo.yml'
   schedule:
     # run daily, this refreshes the cache
     - cron: "13 2 * * *"

doc/README.md

@@ -1,41 +1,32 @@
-# Quick start guide:
+# Quick start guide
 
-- Visit https://xapi-project.github.io/new-docs/ to view the current documentation.
+- 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
+### Supported versions of Hugo and the Hugo Relearn theme
 
-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 Relearn 7.3.2 is currently used (defined by a git tag in `doc/go.mod`).
 
-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
+- The minimum Hugo version required by the Relearn theme is 0.126.0.
+- The current Ubuntu `snap` (which provides 0.142.0) also works.
 
 ## Installation
 
-- Install Hugo; follow the guidance on https://gohugo.io/getting-started/installing.
-  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
+- Install Hugo 0.126 or newer (required by the Hugo Relearn theme)
+  follow the guidance on <https://gohugo.io/installing>.
+  You'll need to install Go as well: see <https://go.dev/>
+  - On Ubuntu, use the `snap` package:
+    - `sudo snap install hugo` installs the current version
+      `apt-get install hugo` would install a version that is too old,
+      (this applies up to Ubuntu 24.04)
 
   - 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:
@@ -47,13 +38,67 @@ Hugo Relearn >= 5.24.0 and < 6.x are expected to work:
 ## Development
 
 - Run a local server: `hugo server`
-- Open a browser at http://127.0.0.1:1313/new-docs/
+- Open a browser at <http://127.0.0.1:1313/new-docs/>
 - Add content to `doc/content/`:
   - Documents are written in Markdown.
-  - Please wrap lines in paragraphs to make review and diffs easier to read.
-  - The menu hierarchy comes mostly from the directory structure in `content/`.
+  - Please wrap lines in paragraphs to make reviews more manageable.
+  - The menu hierarchy comes mainly from the directory structure in `content/`.
   - A file called `_index.md` is needed in a directory to define a new level in the menu.
-    - To set the page title which is also used for the main menu,
+    - To set the page title,
       [use the front matter](https://gohugo.io/content-management/front-matter/).
-  - For a page that has images or other stuff included, it is best to create a new directory. Put the contents in a `index.md` file (no `_`) and the related files next to it. See https://gohugo.io/content-management/organization/ for more information.
-  - Look at https://mcshelby.github.io/hugo-theme-relearn/ for more information about what the Relearn theme offers, including some handy "shortcodes".
+  - For a page that has images or other stuff included, it is best to create a new directory:
+    Put the contents in an `index.md` file (no `_`) and the related files next to it.
+    See <https://gohugo.io/content-management/organization/> for more information.
+
+  See <https://mcshelby.github.io/hugo-theme-relearn/> for more information about
+  the features of the Relearn theme, including handy "shortcodes".
+
+Note: When switching versions, before re-generating the documentation using
+`hugo server`, delete the previously generated static site using `rm -r docs/public`.
+
+### Notes for supporting current versions of Hugo and the Relearn theme
+
+Backported fixes to support newer Hugo versions:
+
+- `layouts/partials/header.html`, it fixes:
+  ```js
+  ERROR deprecated: .Sites.First was deprecated in Hugo v0.127.0 and will be removed in Hugo 0.143.0. Use .Sites.Default instead.
+  ```
+- `layouts/partials/menu.html`, it fixes:
+  ```js
+  ERROR deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.143.0. Use hugo.IsMultilingual instead.
+  ```
+
+The fixes for those issues were backported from the Hugo Relearn v7.x.x theme.
+When updating to Hugo Relearn 7.x.x, please remove them (if possible).
+
+#### Tips when upgradubg to newer Hugo Relearn versions
+
+Check the release notes of the Hugo Relearn theme for breaking changes:
+https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes
+
+These pages might need review when making changes as their content is
+generated by layouts/partials/content.html:
+
+- XenAPI Reference: <https://xapi-project.github.io/new-docs/xen-api/classes>
+- XenAPI Releases: <https://xapi-project.github.io/new-docs/xen-api/releases>
+
+For a summary of the partials supported by the Hugo Relearn theme, see:
+https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/partials
+
+Hint: For upgrading the Hugo Relearn theme, you can use:
+
+```bash
+cd doc; hugo mod get -u github.com/McShelby/[email protected]
+```
+
+#### Summary
+
+Hugo >= 0.126 and the Hugo Relearn >= 7.3.2 are supported to render the docs.
+
+#### References
+
+- Changes with Relearn 6.x:
+  <https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/6/#6-0-0>
+- Breaking changes with Relearn 7.x:
+  <https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/7/#7-0-0>

doc/content/design/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Design Documents"
-menuTitle = "Designs"
+linkTitle = "Designs"
 +++
 
 {{< design_docs_list >}}

doc/content/toolstack/_index.md

@@ -1,6 +1,6 @@
 ---
 title: The XAPI Toolstack
-menuTitle: The Toolstack
+linkTitle: The Toolstack
 weight: 10
 ---
 

doc/content/toolstack/features/events/index.md

@@ -1,6 +1,6 @@
 +++
 title = "Event handling in the Control Plane - Xapi, Xenopsd and Xenstore"
-menuTitle = "Event handling"
+linkTitle = "Event handling"
 +++
 
 Introduction

doc/content/xapi/cli/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "XE CLI architecture"
-menuTitle = "CLI"
+linkTitle = "CLI"
 +++
 
 {{% notice info %}}

doc/content/xapi/memory/index.md

@@ -1,6 +1,6 @@
 +++
 title = "Host memory accounting"
-menuTitle = "Memory"
+linkTitle = "Memory"
 +++
 
 Memory is used for many things:

doc/content/xapi/storage/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "XAPI's Storage Layers"
-menuTitle = "Storage"
+linkTitle = "Storage"
 +++
 
 {{% notice info %}}

doc/content/xapi/walkthroughs/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "XAPI requests walk-throughs"
-menuTitle = "Walk-throughs"
+linkTitle = "Walk-throughs"
 +++
 
 Let's detail the handling process of an XML request within XAPI.