From b318cea56e9e2319edcb65c4d01c06f7d6a2702f Mon Sep 17 00:00:00 2001 From: Bernhard Kaindl Date: Fri, 24 Jan 2025 12:00:00 +0100 Subject: [PATCH] docs: Update README.md and Hugo Relearn to 5.23.0 Minor update of the Hugo documentation: - The current Ubuntu snap of Hugo is currently not supported by the docs. Take a first minor step towards fixing this. - The smallest step is to update the Relearn theme from 5.20.x to 5.23.0: - It does not introduce breaking changes. - It intruduces simpler relative page links and deprecates older syntax - Fix the warnings by updating relative links accordingly --- 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, 53 insertions(+), 9 deletions(-) diff --git a/doc/README.md b/doc/README.md index 01879806e59..19889a96f9a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,9 +1,53 @@ -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 sucessive changes in both Hugo and Relearn, +the docs are only compatible specific versions. + +Currently compatible versions: + +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) +- Hugo Relearn 5.25 currently triggers 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`. + - 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..1432b5fa5a7 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). Replicating the database ------------------------ diff --git a/doc/content/xapi/cli/_index.md b/doc/content/xapi/cli/_index.md index a4ae338390a..a2c6de737a8 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.md) +- [Adding an operation](../guides/howtos/add-function.md) diff --git a/doc/content/xapi/guides/howtos/add-class.md b/doc/content/xapi/guides/howtos/add-class.md index 9e4680059da..467719575c0 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.md) +* [Adding a Function](add-function.md) 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