Fix build errors (link + spelling)

.custom_wordlist.txt

@@ -0,0 +1,32 @@
+airgap
+CAs
+CHP
+deserialise
+gapped
+HTTPS
+HSM
+hostname
+IoT
+libmacaroons
+libpq
+LXD
+Nitrokeys
+OAuth
+OCI
+PKCS
+PostgreSQL
+prem
+pymacaroons
+RESTful
+RSA
+SaaS
+sha
+SHA
+SnapD
+SoftHSMv
+SSO
+subpath
+systemd
+TLS
+walkthrough
+whitepaper

custom_conf.py

@@ -89,7 +89,7 @@
 
     # Change to the GitHub URL for your project
     # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation.
-    'github_url': 'https://github.com/canonical/sphinx-docs-starter-pack',
+    'github_url': 'https://github.com/canonical-ols/snapstore-snap-docs',
 
     # Change to the branch for this version of the documentation
     'github_version': 'main',
@@ -152,6 +152,8 @@
 # Remove this variable to disable the MyST parser extensions.
 custom_myst_extensions = []
 
+myst_heading_anchors = 3
+
 # Add custom Sphinx extensions as needed.
 # This array contains recommended extensions that should be used.
 # NOTE: The following extensions are handled automatically and do

en/airgap-charmhub.md

@@ -50,13 +50,13 @@ Downloading traefik-k8s revision 176 (stable)
 Successfully exported charm bundle cos-lite: /home/ubuntu/snap/store-admin/common/export/cos-lite-20240426T143758.tar.gz
 ```
 
-If not specified, `channel` defaults to `<default-track>/stable`, `series` defaults to `jammy`, and `arch` defaults to `amd64`. If a charm is not found for a given Ubuntu series, the exporter will attempt to fallback or fallforward to the release available for the nearest LTS.
+If not specified, `channel` defaults to `<default-track>/stable`, `series` defaults to `jammy`, and `arch` defaults to `amd64`. If a charm is not found for a given Ubuntu series, the exporter will attempt to fallback or fall forward to the release available for the nearest LTS.
 
-The component charms in the bundle will be auto-exported based on the channel and series defined in the bundle. If it is necessary to modify the bundle before exporting the component charms, then the bundle.yaml can be printed to stdout by passing `--only-print-yaml=True`.
+The component charms in the bundle will be auto-exported based on the channel and series defined in the bundle. If it is necessary to modify the bundle before exporting the component charms, then the `bundle.yaml` can be printed to `stdout` by passing `--only-print-yaml=True`.
 
 ### Export charms
 
-To export individual charms, either start from an existing bundle.yaml or define one with a list of cherry-picked charms. The following shows an example for a custom-defined `charms.yaml` (can be any file name):
+To export individual charms, either start from an existing `bundle.yaml` or define one with a list of cherry-picked charms. The following shows an example for a custom-defined `charms.yaml` (can be any file name):
 
 ```yaml
 applications:
@@ -84,7 +84,7 @@ Downloading resources for postgresql-k8s
 Successfully exported charms to: /home/ubuntu/snap/store-admin/common/export/charms-export-20240426T163115.tar.gz
 ```
 
-The exported tar.gz contains the following:
+The exported `tar.gz` contains the following:
 
 ```bash
 charms-export-20240426T163115.tar.gz/
@@ -100,15 +100,15 @@ charms-export-20240426T163115.tar.gz/
 where:
 
 - `metadata.json` is the charm metadata fetched, this is required by CHP to write the charm's channel map and other metadata to enable deployments.
-- `bundle.yaml` is a copy of the user-specified export .yaml, provided for ease of reference.
+- `bundle.yaml` is a copy of the user-specified export `.yaml`, provided for ease of reference.
 - `postgresql-k8s_20.charm` is the binary downloaded from Charmhub, for the revision resolved.
 - `postgresql-k8s_publisher_account.assert` is the account assertion of the charm publisher.
 - `resources/` contain resource binaries attached to the exported charm revision.
 
 ### Export snap resources
 
 Some charms may require a specific snap revision as a resource. These charms usually run the equivalent of `snap install <snap> --revision <rev>` in their setup code ([example](https://github.com/canonical/postgresql-operator/blob/9614915048ba612bb4be6a5fd8c752a46bb051ed/lib/charms/operator_libs_linux/v2/snap.py#L460)).
-To export snaps by revision, define a .yaml file of the following structure:
+To export snaps by revision, define a `.yaml` file of the following structure:
 
 ```yaml
 packages:
@@ -122,7 +122,7 @@ packages:
 
 When installing a snap by revision, the Snap Store requires that the revision exists in the snap's channel map history, i.e. the revision must have been released to any channel before it can be requested directly. Thus, `push_channel` needs to be specified to tell Snap Store Proxy the target channel for the revision. This can be a channel that exists for the snap, thereby effectively overriding the channel when the snap is pushed, or it can be an arbitrary track, which would be created in the Proxy on push.
 
-The export .yaml can be supplied to the `export snaps` command like so:
+The export `.yaml` can be supplied to the `export snaps` command like so:
 
 ```bash
 $ store-admin export snaps --from-yaml snaps.yaml
@@ -161,9 +161,9 @@ The directory can then be manually copied to the air-gapped registry host, then
 $ skopeo copy dir:/home/ubuntu/<copied-dir> docker://<local-registry-domain>/charm/kotcfrohea62xreenq1q75n1lyspke0qkurhk/postgresql-image@sha256:8a72e1152d4a0... --dest-creds=<local-registry-username>:<local-registry-password>
 ```
 
-By default, if no override is supplied via the `resources` key in the .yaml supplied for charm export, Charmhub Proxy will assume an identical local registry image path (excluding the domain but including `charm/` and including the sha256 tag). When a deployment is requested, CHP will supply a regenerated blob using the local domain URL and credentials configured.
+By default, if no override is supplied via the `resources` key in the `.yaml` supplied for charm export, Charmhub Proxy will assume an identical local registry image path (excluding the domain but including `charm/` and including the sha256 tag). When a deployment is requested, CHP will supply a regenerated blob using the local domain URL and credentials configured.
 
-The `skopeo` commands above pushes the image to the same path in the local registry and saves the effort of manually remapping resources. If required, the image can be pushed to a custom path, but a mapping must be defined for the resource as in the example charms.yaml in [Export charms](#export-charms).
+The `skopeo` commands above pushes the image to the same path in the local registry and saves the effort of manually remapping resources. If required, the image can be pushed to a custom path, but a mapping must be defined for the resource as in the example `charms.yaml` in [Export charms](#export-charms).
 
 ## Import Packages
 Once the exported charm tar file is on the on-prem store host, they should be moved to the
@@ -187,7 +187,7 @@ When re-importing charms or importing other revisions, make sure to provide the
 
 After importing, the charms/bundles are then available to be managed with Juju commands.  
 
-- When importing machine charms that depend on a snap for functionality, you must first manually [import the required snap. ](airgap.html#side-loading-snaps).
+- When importing machine charms that depend on a snap for functionality, you must first manually [import the required snap](airgap.md#side-loading-snaps).
 - When importing Kubernetes charms, ensure that the corresponding OCI image is copied to the local registry, maintaining its original path.
 
 
@@ -196,13 +196,13 @@ After importing, the charms/bundles are then available to be managed with Juju c
 Ensure you have Juju configured along with the necessary cloud environment. 
 
 For production environments, particularly if you need self-signed TLS certificates to function correctly, set up the Juju controller on a non-Kubernetes instance.
-Even if the Juju controller isn't hosted on a Kubernetes cluster, it can still manage Kubernetes models. This flexibility allows the controller to operate from a different environment, such as a virtual machine or an lxd container, while still effectively orchestrating resources within Kubernetes.
+Even if the Juju controller isn't hosted on a Kubernetes cluster, it can still manage Kubernetes models. This flexibility allows the controller to operate from a different environment, such as a virtual machine or an LXD container, while still effectively orchestrating resources within Kubernetes.
 
 
 This setup allows you to incorporate a self-signed certificate within the `cloudinit` configuration, enabling the Juju controller to trust the certificate.
 
 
-First, you need to prepare the Juju configuration file. In this file, override the default URLs for Charmhub and Snapstore. Additionally, if you're using a self-signed certificate for Charmhub, include it in the trusted certificates section of `cloudinit-userdata`. 
+First, you need to prepare the Juju configuration file. In this file, override the default URLs for Charmhub and Snap Store. Additionally, if you're using a self-signed certificate for Charmhub, include it in the trusted certificates section of `cloudinit-userdata`. 
 
 ### Self-signed certificate
 
@@ -212,7 +212,7 @@ You can create a self signed certificate for the Snap store proxy with the follo
 sudo snap-store-proxy import-certificate --selfsigned
 ```
 
-After it's created, you can retrieve the public key from the config:
+After it's created, you can retrieve the public key from the configuration:
 ```bash
 snap-store-proxy config proxy.tls.cert | cat > tls-cert.crt
 ```
@@ -225,7 +225,7 @@ sudo update-ca-certificates
 
 ### Configuration file
 
-Example of a juju configuration yaml. Note that ca-certs list is necessary only when using self-signed certificate for the local Charmhub.
+Example of a Juju configuration `.yaml`. Note that ca-certs list is necessary only when using self-signed certificate for the local Charmhub.
 ```yaml
 cloudinit-userdata: |
   ca-certs:
@@ -250,7 +250,7 @@ juju bootstrap lxd machine-controller --config=/var/snap/juju/common/juju-config
 ```
 
 
-The example below assumes that an LXD cloud is already set up and utilizes it to create a Juju controller:
+The example below assumes that an LXD cloud is already set up and utilises it to create a Juju controller:
 ```bash
 juju add-k8s k8s-cloud --controller=machine-controller 
 ```

en/airgap.md

@@ -40,9 +40,10 @@ can authenticate to such on-prem store and get access to imported brand store
 snaps which are not accessible to any other devices connecting to that on-prem
 store.
 
-!!! Neutral "Note":
-    Client devices have to be equipped with their
-    [serial assertions](devices.md#obtaining-serial-assertions).
+```{note}
+Client devices have to be equipped with their
+[serial assertions](devices.md#obtaining-serial-assertions).
+```
 
 ## Installation
 
@@ -54,13 +55,14 @@ followed by airgap mode activation:
 sudo snap-proxy enable-airgap-mode
 ```
 
-!!! Negative "":
-    Even though it's possible to enable airgap mode for an online proxy, it's
-    only advised to do so during the installation phase when no devices are yet
-    [connected](devices.md) to the proxy. Deactivating and activating airgap
-    mode while it's already serving clients will have undesirable and not
-    clearly defined consequences for the devices that were connected to it
-    before the mode switch as well as for the snap-store-proxy instance itself.
+```{note}
+Even though it's possible to enable airgap mode for an online proxy, it's
+only advised to do so during the installation phase when no devices are yet
+[connected](devices.md) to the proxy. Deactivating and activating airgap
+mode while it's already serving clients will have undesirable and not
+clearly defined consequences for the devices that were connected to it
+before the mode switch as well as for the snap-store-proxy instance itself.
+```
 
 ### Offline installation
 
@@ -85,11 +87,12 @@ an offline host (partly pre-configured as well):
 store-admin register --offline <target-http-location-of-the-store>
 ```
 
-!!! Warning "":
+```{warning}
     Full value of the target location, eg `https://snaps.internal`, will be encoded
     in an assertion file used for instructing client devices to connect to this
     store. It's important to decide if http or https will be used and what the host
     name will be at the point of registration.
+```
 
 The result of the above is a tarball `offline-snap-store.tar.gz` that is then
 moved to the target host machine for the offline store for installation.
@@ -130,10 +133,11 @@ If the registered store's location was an HTTPS one, follow the
 
 ## Brand store metadata import
 
-!!! Warning "":
+```{warning}
     This section is relevant for brand store customers wanting to host their
     brand store snaps offline and can be skipped if the offline store only has
     to support Global store client devices (eg. generic devices).
+```
 
 On-prem stores need various data (assertions, snap binaries and metadata,
 account information) - produced by the upstream Snap Store - to function. This
@@ -243,15 +247,15 @@ htop: htop-20221026T104628.tar.gz
 This produces a set of `tar.gz` files (one per snap name) that have to be moved
 to the on-prem store host and imported there.
 
-!!! Positive "":
-    By default snaps are exported from the Global store, and then imported as
-    such, meaning that any device connected to the on-prem store will be able to
-    install them (if it's configured to use the default Global store).
-    `store-admin export snaps` has a `--store` option allowing for authenticated
-    export of snaps from private device-view IoT App Stores - after importing
-    these, snaps will be accessible only to properly authenticated devices from
-    the relevant brand.
-
+```{note}
+By default snaps are exported from the Global store, and then imported as
+such, meaning that any device connected to the on-prem store will be able to
+install them (if it's configured to use the default Global store).
+`store-admin export snaps` has a `--store` option allowing for authenticated
+export of snaps from private device-view IoT App Stores - after importing
+these, snaps will be accessible only to properly authenticated devices from
+the relevant brand.
+```
 
 ### Importing (pushing) snaps
 
@@ -309,7 +313,7 @@ online Snap Store Proxy.
 ## Offline Upgrades
 
 To upgrade snap-store-proxy on an offline machine, first download the snap and
-its assertions on a machine with internet access, eg:
+its assertions on a machine with internet access, e.g.:
 
 
 ```bash
@@ -325,14 +329,14 @@ sudo snap ack snap-store-proxy_<revision>.assert
 sudo snap install snap-store-proxy_<revision>.snap
 ```
 
-And use analogous process to upgrade the base and snapd snaps.
+And use analogous process to upgrade the base and `snapd` snaps.
 
 
 ## Configuration backup
 
 Make sure to securely backup the snap-store-proxy configuration (including the
-proxy.device-auth.secret used for signing/verifying the device sessions). The
-config can be exported with:
+`proxy.device-auth.secret` used for signing/verifying the device sessions). The
+configuration can be exported with:
 
 ```bash
 sudo snap-store-proxy config > proxy-config-backup.txt