From 458b1386ea9b9a95d08ede71f38f0fa09a4f156a Mon Sep 17 00:00:00 2001 From: Bernhard Kaindl Date: Fri, 24 Jan 2025 12:00:00 +0100 Subject: [PATCH 1/3] 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 --- doc/README.md | 48 +++++++++++++++++++-- doc/content/design/cpu-levelling-v2.md | 2 +- doc/content/design/local-database.md | 2 +- doc/content/xapi/cli/_index.md | 4 +- doc/content/xapi/guides/howtos/add-class.md | 4 +- doc/go.mod | 2 +- 6 files changed, 52 insertions(+), 10 deletions(-) diff --git a/doc/README.md b/doc/README.md index 01879806e59..a2d2c7f531d 100644 --- a/doc/README.md +++ b/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/`: diff --git a/doc/content/design/cpu-levelling-v2.md b/doc/content/design/cpu-levelling-v2.md index 2192c1665a3..48e52afcf63 100644 --- a/doc/content/design/cpu-levelling-v2.md +++ b/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 diff --git a/doc/content/design/local-database.md b/doc/content/design/local-database.md index 2393df63760..6480e2a6b58 100644 --- a/doc/content/design/local-database.md +++ b/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 ------------------------ diff --git a/doc/content/xapi/cli/_index.md b/doc/content/xapi/cli/_index.md index a4ae338390a..d2aba33e30d 100644 --- a/doc/content/xapi/cli/_index.md +++ b/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) diff --git a/doc/content/xapi/guides/howtos/add-class.md b/doc/content/xapi/guides/howtos/add-class.md index 9e4680059da..aee29a69429 100644 --- a/doc/content/xapi/guides/howtos/add-class.md +++ b/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 diff --git a/doc/go.mod b/doc/go.mod index 2a4ecc5844d..2e145daa17e 100644 --- a/doc/go.mod +++ b/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 From 7010a98971290f19062d89a9edad2ab2dea0ea9c Mon Sep 17 00:00:00 2001 From: Bernhard Kaindl Date: Fri, 24 Jan 2025 12:00:00 +0100 Subject: [PATCH 2/3] Fix currently broken links to toolstack/features: HA, snapshots Signed-off-by: Bernhard Kaindl --- doc/content/design/multiple-cluster-managers.md | 4 ++-- doc/content/design/ocfs2/index.md | 2 +- doc/content/xen-api/topics/snapshots.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/content/design/multiple-cluster-managers.md b/doc/content/design/multiple-cluster-managers.md index 6c0e783fe66..458fac47c8b 100644 --- a/doc/content/design/multiple-cluster-managers.md +++ b/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 `/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). diff --git a/doc/content/design/ocfs2/index.md b/doc/content/design/ocfs2/index.md index c8d0852e0a9..c21dfda8280 100644 --- a/doc/content/design/ocfs2/index.md +++ b/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 diff --git a/doc/content/xen-api/topics/snapshots.md b/doc/content/xen-api/topics/snapshots.md index 91b5969ce42..4e6d042420a 100644 --- a/doc/content/xen-api/topics/snapshots.md +++ b/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 ===================== From 26264f90f23eb8f3a60f34e4963af3207d808946 Mon Sep 17 00:00:00 2001 From: Bernhard Kaindl Date: Fri, 24 Jan 2025 12:00:00 +0100 Subject: [PATCH 3/3] Update 3 links to the hierachy of the new-docs site Signed-off-by: Bernhard Kaindl --- doc/content/toolstack/features/DR/index.md | 2 +- doc/content/toolstack/features/snapshots/index.md | 2 +- doc/content/xenopsd/architecture/_index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/content/toolstack/features/DR/index.md b/doc/content/toolstack/features/DR/index.md index a958cb9f27a..5a6ddc7dbc8 100644 --- a/doc/content/toolstack/features/DR/index.md +++ b/doc/content/toolstack/features/DR/index.md @@ -2,7 +2,7 @@ title = "Disaster Recovery" +++ -The [HA](../HA/HA.html) feature will restart VMs after hosts have failed, but what +The [HA](HA) feature will restart VMs after hosts have failed, but what happens if a whole site (e.g. datacenter) is lost? A disaster recovery configuration is shown in the following diagram: diff --git a/doc/content/toolstack/features/snapshots/index.md b/doc/content/toolstack/features/snapshots/index.md index 789f35fa1f6..05185f53df9 100644 --- a/doc/content/toolstack/features/snapshots/index.md +++ b/doc/content/toolstack/features/snapshots/index.md @@ -8,7 +8,7 @@ Snapshots represent the state of a VM, or a disk (VDI) at a point in time. They - experiments (take snapshot, try something, revert back again) - golden images (install OS, get it just right, clone it 1000s of times) -Read more about [the Snapshot APIs](../../xen-api/snapshots.html). +Read more about [the Snapshot APIs](../../../xen-api/topics/snapshots). Disk snapshots ============== diff --git a/doc/content/xenopsd/architecture/_index.md b/doc/content/xenopsd/architecture/_index.md index 4c70bdca2e8..0f4d5eccea5 100644 --- a/doc/content/xenopsd/architecture/_index.md +++ b/doc/content/xenopsd/architecture/_index.md @@ -17,7 +17,7 @@ Managing a VM means: - providing updates to clients when things change (reboots, console becomes available, guest agent says something etc). -For a full list of features, consult the [features list](features.html). +For a full list of features, consult the [feature list](../features). Each Xenopsd instance has a unique name on the host. A typical name is