From d3bef4b2b3c1878583b9efb66abb17fe0b352716 Mon Sep 17 00:00:00 2001 From: Graham Morrison Date: Mon, 9 Mar 2026 16:02:46 +0000 Subject: [PATCH 1/6] removed commented out code --- docs/jobs/pre-build-job.sh | 66 +++++++++++++++++++------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/jobs/pre-build-job.sh b/docs/jobs/pre-build-job.sh index 0f77f41..8e11788 100644 --- a/docs/jobs/pre-build-job.sh +++ b/docs/jobs/pre-build-job.sh @@ -7,38 +7,38 @@ WORKFLOW="build-documentation.yaml" ARTIFACT_NAME="openapi-spec" # Updated to match the new GitHub Action output TARGET_DIR="${SOURCEDIR}/_html_extra/reference/api" -# mkdir -p "${TARGET_DIR}" -# -# echo "Searching for the latest successful run that has artifact '${ARTIFACT_NAME}'..." -# -# RUN_IDS=$(gh run list \ -# -R "${REPO}" \ -# --workflow "${WORKFLOW}" \ -# --status success \ -# --limit 100 \ -# --json databaseId \ -# -q '.[].databaseId') -# -# DOWNLOAD_SUCCESS=false -# -# for id in $RUN_IDS; do -# echo -n "Checking Run ID $id... " -# -# # Download the artifact contents directly into the target directory -# gh run download "$id" -R "${REPO}" -n "${ARTIFACT_NAME}" -D "${TARGET_DIR}" >/dev/null 2>&1 -# -# if [ $? -eq 0 ]; then -# echo "Found and downloaded!" -# DOWNLOAD_SUCCESS=true -# break -# else -# echo "Artifact not found (skipped)." -# fi -# done -# -# if [ "$DOWNLOAD_SUCCESS" = false ]; then -# echo "Error: Checked the last 100 successful runs, but none contained the artifact '${ARTIFACT_NAME}'." -# exit 1 -# fi +mkdir -p "${TARGET_DIR}" + +echo "Searching for the latest successful run that has artifact '${ARTIFACT_NAME}'..." + +RUN_IDS=$(gh run list \ + -R "${REPO}" \ + --workflow "${WORKFLOW}" \ + --status success \ + --limit 100 \ + --json databaseId \ + -q '.[].databaseId') + +DOWNLOAD_SUCCESS=false + +for id in $RUN_IDS; do + echo -n "Checking Run ID $id... " + + # Download the artifact contents directly into the target directory + gh run download "$id" -R "${REPO}" -n "${ARTIFACT_NAME}" -D "${TARGET_DIR}" >/dev/null 2>&1 + + if [ $? -eq 0 ]; then + echo "Found and downloaded!" + DOWNLOAD_SUCCESS=true + break + else + echo "Artifact not found (skipped)." + fi +done + +if [ "$DOWNLOAD_SUCCESS" = false ]; then + echo "Error: Checked the last 100 successful runs, but none contained the artifact '${ARTIFACT_NAME}'." + exit 1 +fi echo "OpenAPI spec successfully downloaded to ${TARGET_DIR}/openapi.json" From 690b5c386daeb6443d1f543d14c89cd57f6effea Mon Sep 17 00:00:00 2001 From: Graham Morrison Date: Wed, 11 Mar 2026 15:46:55 +0000 Subject: [PATCH 2/6] Add HTML meta descriptions to documentation index files for improved SEO. --- docs/explanation/index.md | 6 ++++++ docs/how-to-guides/index.md | 6 ++++++ docs/index.md | 6 ++++++ docs/reference/index.md | 6 ++++++ docs/tutorials/index.md | 6 ++++++ 5 files changed, 30 insertions(+) diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 5fe1357..0a17639 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Explanatory and conceptual guides for snap packages - discussion and clarification of key topics for snap users and snap package developers, including how snaps work, interface connections, update management and security. +--- + (explanation-index)= # Explanation diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 30c4bf7..f6b503c 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Step-by-step guides covering key operations and common tasks for snap users and snap package developers, including how to manage updates, connect interfaces, control services and more. +---Step-by-step guides covering key operations and common tasks for snap users and snap package developers, including how to manage updates, connect interfaces, control services and more. + (how-to-guides-index)= # How-to guides diff --git a/docs/index.md b/docs/index.md index 1a7f123..3b1e83f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Official snap packaging documentation - comprehensive guides for installation, configuration, security, package updates and removal management, alongside technical details on all snap packaging features for snap users and snap package developers. +--- + (ref-index_snap-documentation)= # Snap documentation diff --git a/docs/reference/index.md b/docs/reference/index.md index b6b15e9..f1c155b 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Complete reference documentation for snap packages - technical details on all snap packaging features for snap users and snap package developers, including the snapd REST API, YAML schemas, system architecture and more. +--- + (reference-index)= # Reference diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 41e1ec1..f4d3035 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Getting started with snap packages - learn how to install the snap daemon, and install and configure your first snap packages with step-by-step tutorials. +--- + (tutorials-index)= # Tutorials From 8acfc3a2119814a72ed19585c222823beba67612 Mon Sep 17 00:00:00 2001 From: Graham Morrison Date: Wed, 11 Mar 2026 18:58:21 +0000 Subject: [PATCH 3/6] Add HTML meta descriptions to all secondary landing pages for improved SEO and clarity. --- docs/explanation/how-snaps-work/index.md | 6 ++++++ docs/explanation/interfaces/index.md | 7 ++++++- docs/explanation/security/index.md | 6 ++++++ docs/how-to-guides/index.md | 2 +- docs/how-to-guides/manage-snaps/index.md | 6 ++++++ docs/how-to-guides/snap-development/index.md | 6 ++++++ docs/reference/administration/index.md | 6 ++++++ docs/reference/development/index.md | 6 ++++++ docs/reference/development/yaml-schemas/index.md | 6 ++++++ docs/reference/interfaces/index.md | 6 ++++++ docs/tutorials/get-started.md | 7 +++++++ docs/tutorials/install-the-daemon/index.md | 6 ++++++ 12 files changed, 68 insertions(+), 2 deletions(-) diff --git a/docs/explanation/how-snaps-work/index.md b/docs/explanation/how-snaps-work/index.md index af5c24d..3d47f0a 100644 --- a/docs/explanation/how-snaps-work/index.md +++ b/docs/explanation/how-snaps-work/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Explanatory and conceptual guides for snap packages - discussion and clarification of key topics for snap users and snap package developers, including how snaps work, interface connections, update management and security. +--- + (explanation-how-snaps-work-index)= # How snaps work diff --git a/docs/explanation/interfaces/index.md b/docs/explanation/interfaces/index.md index 423d348..4dced91 100644 --- a/docs/explanation/interfaces/index.md +++ b/docs/explanation/interfaces/index.md @@ -1,7 +1,12 @@ +--- +myst: + html_meta: + description: Explanations of how the snap interface system works, including how interfaces are used to manage access to resources, and how interface hooks can be used to control what happens when an interface is used. +--- + (explanation-interfaces-index)= # Interfaces - As you begin to use snaps more, interfaces can be used to carefully permit and limit access to resources. * {ref}`All about interfaces `: The permission system used to manage access to resources. diff --git a/docs/explanation/security/index.md b/docs/explanation/security/index.md index eeba3ad..6844141 100644 --- a/docs/explanation/security/index.md +++ b/docs/explanation/security/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Learn about how snaps use standard Linux security policies to isolate themselves from the system, and from each other. Understand snap confinement, security policies and the snapd release process. +--- + (explanation-security-index)= # Security diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index f6b503c..e56a5e6 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -2,7 +2,7 @@ myst: html_meta: description: Step-by-step guides covering key operations and common tasks for snap users and snap package developers, including how to manage updates, connect interfaces, control services and more. ----Step-by-step guides covering key operations and common tasks for snap users and snap package developers, including how to manage updates, connect interfaces, control services and more. +--- (how-to-guides-index)= # How-to guides diff --git a/docs/how-to-guides/manage-snaps/index.md b/docs/how-to-guides/manage-snaps/index.md index 148c358..81a343a 100644 --- a/docs/how-to-guides/manage-snaps/index.md +++ b/docs/how-to-guides/manage-snaps/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Step-by-step guides on how to manage snap packages - control when snaps update, connect interfaces, set system options, control services and more for snap users and snap package developers. +--- + (how-to-guides-manage-snaps-index)= # Manage snaps diff --git a/docs/how-to-guides/snap-development/index.md b/docs/how-to-guides/snap-development/index.md index 973b4b3..061efce 100644 --- a/docs/how-to-guides/snap-development/index.md +++ b/docs/how-to-guides/snap-development/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Extend snap functionality with API access, internal tools, and customised environments for your applications and devices. Learn how to use the SnapD REST API, snapctl, test snapd fixes, debug snaps, use snap try and in-development features. +--- + (how-to-snap-development)= # Snap development diff --git a/docs/reference/administration/index.md b/docs/reference/administration/index.md index 28377d4..0a876e1 100644 --- a/docs/reference/administration/index.md +++ b/docs/reference/administration/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Deepen your understanding of how snaps can run on all kinds of devices, in all kinds of environments. Learn about system options, data locations, distribution support, network requirements and more for snap users and snap package developers. +--- + (reference-administration-index)= # Administration diff --git a/docs/reference/development/index.md b/docs/reference/development/index.md index 6e255c8..dea8559 100644 --- a/docs/reference/development/index.md +++ b/docs/reference/development/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Extend snap functionality with API access and customised environments for your applications and devices. Learn about environment variables, the SnapD REST API, YAML schemas and more for snap users and snap package developers. +--- + (reference-development-index)= # Development diff --git a/docs/reference/development/yaml-schemas/index.md b/docs/reference/development/yaml-schemas/index.md index ed25ebf..c805ccd 100644 --- a/docs/reference/development/yaml-schemas/index.md +++ b/docs/reference/development/yaml-schemas/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: YAML schemas for snap packages, including the snap.yaml format, and the gadget and kernel snap formats for device development. +--- + (reference-development-yaml-schemas-index)= # YAML schemas diff --git a/docs/reference/interfaces/index.md b/docs/reference/interfaces/index.md index 490a083..1bf0eca 100644 --- a/docs/reference/interfaces/index.md +++ b/docs/reference/interfaces/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Every snap interface in a single place. Learn about the interfaces available to snap users and snap package developers, including how they work, how to use them, and how to manage them. +--- + (ref-index_interfaces)= # Interfaces diff --git a/docs/tutorials/get-started.md b/docs/tutorials/get-started.md index 0c5f091..7de8f27 100644 --- a/docs/tutorials/get-started.md +++ b/docs/tutorials/get-started.md @@ -1,3 +1,10 @@ +--- +myst: + html_meta: + description: Learn how to list, find, install, run, update and remove snap packages with a hands-on introduction to using snap packages for new users. +--- + + (tutorials-get-started)= # Get started diff --git a/docs/tutorials/install-the-daemon/index.md b/docs/tutorials/install-the-daemon/index.md index 669223e..8e44797 100644 --- a/docs/tutorials/install-the-daemon/index.md +++ b/docs/tutorials/install-the-daemon/index.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Installation instructions for the snap daemon (snapd) - the background service that manages and maintains your snaps. Snapd is pre-installed on many Linux distributions, and easy to install on most others. Find installation instructions for your distribution here. +--- + (tutorials-install-the-daemon-index)= # Install the daemon From 61dba02c1865051323c2069d2d7dc760fbf5f689 Mon Sep 17 00:00:00 2001 From: Graham Morrison Date: Thu, 12 Mar 2026 09:45:41 +0000 Subject: [PATCH 4/6] fixes #171 --- .../explanation/how-snaps-work/snap-performance.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/explanation/how-snaps-work/snap-performance.md b/docs/explanation/how-snaps-work/snap-performance.md index d3021bc..411ef36 100644 --- a/docs/explanation/how-snaps-work/snap-performance.md +++ b/docs/explanation/how-snaps-work/snap-performance.md @@ -1,3 +1,9 @@ +--- +myst: + html_meta: + description: Snap performance analysis, including snap debug timing and SquashFS performance and compression. +--- + (explanation-how-snaps-work-snap-performance)= # Snap performance @@ -46,9 +52,6 @@ The following charts were produced from the `Doing` column output of `snap debu ![Chromium snap cached install timing data](https://assets.ubuntu.com/v1/54cae8e8-chromium-cached-install-pie.png) - -```{dropdown} Debug timing data for cached install of Chromium snap - ``` ID Status Doing Undoing Label Summary 160241 Done 461ms - prerequisites Ensure prerequisites for "chromium" are available @@ -114,8 +117,6 @@ ID Status Doing Undoing Label Summary ![Chromium snap cold install timing data](https://assets.ubuntu.com/v1/49e70e0e-chromium-cold-install-pie.png) -```{dropdown} Debug timing data for cold install of Chromium snap - ``` ID Status Doing Undoing Label Summary 160162 Done 750ms - prerequisites Ensure prerequisites for "chromium" are available @@ -246,5 +247,4 @@ Compression ratios for various compression algorithms are also affected by the s ![compression ratios comparison](https://assets.ubuntu.com/v1/ddc43d34-compression-ratios-barchart.png) -These comparisons ultimately led to the addition of lzo as an optional compression algorithm, but its use with snaps is entirely dependent on the type and structure of the files within the SquashFS archive. - +These comparisons ultimately led to the addition of lzo as an optional compression algorithm, but its use with snaps is entirely dependent on the type and structure of the files within the SquashFS archive. \ No newline at end of file From 54bd55b36c53c5c44cfd39030aacc7ec4d81de2a Mon Sep 17 00:00:00 2001 From: Graham Morrison Date: Thu, 12 Mar 2026 11:49:11 +0000 Subject: [PATCH 5/6] fixes #175 --- docs/tutorials/install-the-daemon/linux-mint.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/install-the-daemon/linux-mint.md b/docs/tutorials/install-the-daemon/linux-mint.md index 0a73501..1d912a7 100644 --- a/docs/tutorials/install-the-daemon/linux-mint.md +++ b/docs/tutorials/install-the-daemon/linux-mint.md @@ -7,10 +7,10 @@ You can find out which version of Linux Mint you're running by opening *System i From Linux Mint 20 onwards, installing Snap is blocked by a file called `nosnap.pref` in the directory `/etc/apt/preferences.d/`; this file needs to be either moved or removed from the directory, or renamed with an extension other than `.pref` before Snap can be installed. -This can be accomplished from the command line, and the following command (for example) renames `nosnap.pref` to `nosnap.backup`: +This can be accomplished from the command line, and the following command (for example) renames `nosnap.pref` to `nosnap.bak`: ``` -sudo mv /etc/apt/preferences.d/nosnap.pref /etc/apt/preferences.d/nosnap.backup +sudo mv /etc/apt/preferences.d/nosnap.pref /etc/apt/preferences.d/nosnap.bak ``` With the file renamed, the package database needs to be updated next: From ebebe0684da9c5ae234ecccf12dced8490ed9333 Mon Sep 17 00:00:00 2001 From: Graham Morrison Date: Thu, 12 Mar 2026 11:57:07 +0000 Subject: [PATCH 6/6] fixes #45 --- docs/how-to-guides/manage-snaps/use-resource-quotas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/manage-snaps/use-resource-quotas.md b/docs/how-to-guides/manage-snaps/use-resource-quotas.md index 1f8de82..0c4fb25 100644 --- a/docs/how-to-guides/manage-snaps/use-resource-quotas.md +++ b/docs/how-to-guides/manage-snaps/use-resource-quotas.md @@ -70,7 +70,7 @@ sudo snap set-quota loggroup --journal-size=64MB Limit the number of messages logged to a maximum per time period. This is a useful way of limiting the number of messages for snaps. -The time period is can be nanoseconds(us), milliseconds (ms), seconds(s), minutes (m), and hours(h), including aggregated periods: +The time period can be milliseconds (ms), seconds(s), minutes (m), and hours(h), including aggregated periods: ``` sudo snap set-quota loggroup --journal-rate-limit=10/1h2m3s4ms5us