Fix automatic doc checks (#1016)

* fix spellcheck errors and false positives

* fix broken ULRs

* fix remaining broken URLs

* replace leftover mentions of 14/stable with 16/edge

* add newline to custom wordlist file

* fix incorrect VM mentions

* fix typo

Co-authored-by: Carl Csaposs <[email protected]>

---------

Co-authored-by: Carl Csaposs <[email protected]>

Author: a-velasco

docs/.custom_wordlist.txt

@@ -1,40 +1,140 @@
 # Leave a blank line at the end of this file to support concatenation
+airgap
+airgapped
+analyze
+artifact
+Artifactory
+artifacts
+async
+aws
+AWS
+AZ
+AZs
 backend
 backends
+balancer
+balancers
+benchmark
+benchmarking
+CharmBase
 Charmcraft
+charmhub
+checksum
+checksums
+CIS
 cjk
+codebase
+config
+configs
 cryptographically
+CSR
+CSRs
+databag
+databags
+dev
 dvipng
+eks
+EKS
+entrypoint
+failover
+filesystem
+filesystems
 fonts
 freefont
+gapped
+gce
+GCE
+gcloud
+GCloud
+GCP
 github
+GLAuth
 GPG
 gyre
+HLD
+hostname
+hostnames
 https
+IAAS
+integration
+integrations
 Intersphinx
+io
+IPv
+Jira
+jitter
+Juju
+Juju's
 lang
 LaTeX
 latexmk
+LDAP
+libs
+lifecycle
+MicroK8s
+MinIO
 Multipass
+nameserver
+nameservers
+Nextcloud
 otf
+Parca
+Patroni
+Patroni*
+pgbackrest
+pgBackRest
+pgbouncer
+Pgbouncer*
+pgsql
+PITR
 plantuml
 PNG
+pooler
+postgres
+postgresql
+PPA
+PPAs
+pqsql
+programmatically
+PVCs
+py
 Pygments
 QEMU
+RadosGW
+requirer
+rockcraft
 Rockcraft
 rst
+scalable
+sdk
+SHA
+snap
+snapcraft
+SquashFS
+src
+SSL
+stateful
 SVG
+Sysbench
+terraform
 tex
 texlive
 TOC
 toctree
 txt
+ubuntu
 uncommenting
+uncordon
 utils
+vm
 VMs
+WAL
+walkthrough
 WCAG
 whitespace
 whitespaces
 wordlist
 xetex
+XID
 xindy
+yaml

docs/.sphinx/spellingcheck.yaml

@@ -9,7 +9,7 @@ matrix:
         - .custom_wordlist.txt
       output: .sphinx/.wordlist.dic
     sources:
-      - _build/**/*.html
+      - _build/**/*.html|!_build/reference/alert-rules/index.html
     pipeline:
       - pyspelling.filters.html:
           comments: false

docs/conf.py

@@ -207,7 +207,7 @@
 
 linkcheck_ignore = [
     "http://127.0.0.1:8000",
-    "https://github.com/canonical/ACME/*",
+    "https://github.com/canonical/*",
     "https://matrix.to/*"
     ]
 

docs/explanation/architecture.md

@@ -6,7 +6,7 @@
 
 ## Juju K8s concept
 
-The charm design leverages the [sidecar](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/#example-1-sidecar-containers) pattern to allow multiple containers in each pod with [Pebble](https://juju.is/docs/sdk/pebble) running as the workload container’s entrypoint.
+The charm design leverages the [sidecar](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/#example-1-sidecar-containers) pattern to allow multiple containers in each pod with [Pebble](https://documentation.ubuntu.com/juju/3.6/reference/pebble/) running as the workload container’s entrypoint.
 
 Pebble is a lightweight, API-driven process supervisor that is responsible for configuring processes to run in a container and controlling those processes throughout the workload lifecycle.
 
@@ -28,23 +28,23 @@ And if you run `kubectl describe pod postgresql-k8s-0`, all the containers will
 
 ## HLD (High Level Design)
 
-The Charmed PostgreSQL K8s (`workload` container) based on `postgresql-image` resource defined in the [charm metadata.yaml](https://github.com/canonical/postgresql-k8s-operator/blob/main/metadata.yaml). It is an official Canonical [charmed-postgresql](https://github.com/canonical/charmed-postgresql-rock) [OCI/Rock](https://ubuntu.com/server/docs/rock-images/introduction) image, which is recursively based on the Canonical [`charmed-postgresql` snap].
+The Charmed PostgreSQL K8s (`workload` container) based on `postgresql-image` resource defined in the [charm metadata.yaml](https://github.com/canonical/postgresql-k8s-operator/blob/main/metadata.yaml). It is an official Canonical [charmed-postgresql](https://github.com/canonical/charmed-postgresql-rock) [OCI/Rock](https://documentation.ubuntu.com/rockcraft/en/latest/explanation/rockcraft/) image, which is based on the Canonical [`charmed-postgresql` snap].
 
-[Charmcraft](https://juju.is/docs/sdk/install-charmcraft) uploads an image as a [charm resource](https://charmhub.io/postgresql-k8s/resources/postgresql-image) to [Charmhub](https://charmhub.io/postgresql-k8s) during the [publishing](https://github.com/canonical/postgresql-k8s-operator/blob/main/.github/workflows/release.yaml), as described in the [Juju SDK How-to guides](https://juju.is/docs/sdk/publishing).
+[Charmcraft](https://canonical-charmcraft.readthedocs-hosted.com/stable/) uploads an image as a [charm resource](https://charmhub.io/postgresql-k8s/resources/postgresql-image) to [Charmhub](https://charmhub.io/postgresql-k8s) during the [publishing](https://github.com/canonical/postgresql-k8s-operator/blob/main/.github/workflows/release.yaml).
 
-The charm supports Juju deploymed to all Kubernetes environments: [MicroK8s](https://microk8s.io/), [Charmed Kubernetes](https://ubuntu.com/kubernetes/charmed-k8s), [GKE](https://charmhub.io/postgresql-k8s/docs/h-deploy-gke), [Amazon EKS](https://aws.amazon.com/eks/), ...
+The charm supports Juju deployment on all Kubernetes environments: [MicroK8s](https://microk8s.io/), [Charmed Kubernetes](https://ubuntu.com/kubernetes/charmed-k8s), [GKE](/how-to/deploy/gke), [Amazon EKS](/how-to/deploy/aks)...
 
 The OCI/Rock ships the following components:
 
 * PostgreSQL Community Edition (based on [`charmed-postgresql` snap]) 
 * Patroni (based on [`charmed-postgresql` snap]) 
 * PgBouncer (based on [`charmed-postgresql` snap]) 
-* pgBackRest (based on [`charmed-postgresql` snap]) 
+* PgBackRest (based on [`charmed-postgresql` snap]) 
 * Prometheus PostgreSQL Exporter (based on [`charmed-postgresql` snap]) 
 * Prometheus PgBouncer Exporter (based on [`charmed-postgresql` snap]) 
 * Prometheus Grafana dashboards and Loki alert rules are part of the charm revision (and missing in SNAP).
 
-SNAP-based rock images guarantee the same components versions and functionality between VM and K8s charm flavors.
+SNAP-based rock images guarantee the same components versions and functionality between VM and K8s charm flavours.
 
 Pebble runs layers of all the currently enabled services, e.g. monitoring, backups, etc: 
 ```text
@@ -84,7 +84,7 @@ The rock "charmed-postgresql" also ships list of tools used by charm:
 
 ### Data Integrator
 
-[Data Integrator](https://charmhub.io/data-integrator) charm is a solution to request DB credentials for non-native Juju applications. Not all applications implement a data_interfaces relation but allow setting credentials via config. Also, some of the applications are run outside of juju. This integrator charm allows receiving credentials which can be passed into application config directly without implementing juju-native relation.
+[Data Integrator](https://charmhub.io/data-integrator) charm is a solution to request DB credentials for non-native Juju applications. Not all applications implement a data_interfaces relation but allow setting credentials via config. Also, some of the applications are run outside of juju. This integrator charm allows receiving credentials which can be passed into application configuration directly without implementing juju-native relation.
 
 ### PostgreSQL Test App
 
@@ -96,7 +96,7 @@ GLAuth is a secure, easy-to-use and open-sourced LDAP server which provides capa
 
 ### Grafana
 
-Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) setup.
+Grafana is an open-source visualisation tools that allows to query, visualise, alert on, and visualise metrics from mixed data sources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) setup.
 
 ### Loki
 
@@ -108,33 +108,32 @@ Prometheus is an open-source systems monitoring and alerting toolkit with a dime
 
 ## LLD (Low Level Design)
 
-Please check the charm state machines displayed on [workflow diagrams](/explanation/flowcharts/charm). The low-level logic is mostly common for both VM and K8s charm flavors.
+Please check the charm state machines displayed on [workflow diagrams](/explanation/flowcharts/charm). The low-level logic is mostly common for both VM and K8s charm flavours.
 
 <!--- TODO: Describe all possible installations? Cross-model/controller? --->
 
-### Juju Events
+### Juju events
 
-Accordingly to the [Juju SDK](https://juju.is/docs/sdk/event): “an event is a data structure that encapsulates part of the execution context of a charm”.
+An event is a data structure that encapsulates part of the execution context of a charm.
 
 For this charm, the following events are observed:
 
-1. [postgresql_pebble_ready](https://juju.is/docs/sdk/container-name-pebble-ready-event): informs charm about the availability of the rock "charmed-postgresql"-based `workload` K8s container. Also performs basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster). 
-2. [leader-elected](https://juju.is/docs/sdk/leader-elected-event): generate all the secrets to bootstrap the cluster.
-5. [config_changed](https://juju.is/docs/sdk/config-changed-event): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
-6. [update-status](https://juju.is/docs/sdk/update-status-event): Takes care of workload health checks.
+1. [postgresql_pebble_ready](https://documentation.ubuntu.com/juju/3.6/reference/hook/#container-pebble-ready): informs charm about the availability of the rock "charmed-postgresql"-based `workload` K8s container. Also performs basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster). 
+2. [leader-elected](https://documentation.ubuntu.com/juju/3.6/reference/hook/#leader-elected): generate all the secrets to bootstrap the cluster.
+5. [config_changed](https://documentation.ubuntu.com/juju/3.6/reference/hook/#config-changed): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
+6. [update-status](https://documentation.ubuntu.com/juju/3.6/reference/hook/#update-status): Takes care of workload health checks.
 <!--- 7. database_storage_detaching: TODO: ops? event?
-8. TODO: any other events? relation_joined/changed/created/broken
+1. TODO: any other events? relation_joined/changed/created/broken
 --->
 
 ### Charm Code Overview
 
 The "[src/charm.py](https://github.com/canonical/postgresql-k8s-operator/blob/main/src/charm.py)" is the default entry point for a charm and has the `PostgresqlOperatorCharm` Python class which inherits from CharmBase.
 
-CharmBase is the base class from which all Charms are formed, defined by [Ops](https://juju.is/docs/sdk/ops) (Python framework for developing charms). See more information in [Charm](https://juju.is/docs/sdk/constructs#charm).
-
+CharmBase is the base class from which all Charms are formed, defined by [Ops](https://ops.readthedocs.io/en/latest/index.html) (Python framework for developing charms).
 The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.
 
-The VM and K8s charm flavors shares the codebase via [charm libraries](https://juju.is/docs/sdk/libraries) in [lib/charms/postgresql_k8s/v0/](https://github.com/canonical/postgresql-k8s-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py) (of K8s flavor of the charm!):
+The VM and K8s charm flavours shares the codebase via charm libraries in [lib/charms/postgresql_k8s/v0/](https://github.com/canonical/postgresql-k8s-operator/blob/main/lib/charms/postgresql_k8s/v0/postgresql.py) (of K8s flavour of the charm!):
 ```
 > charmcraft list-lib postgresql-k8s                                                                                                                                                                                                               
 Library name    API    Patch                                                                                                                                                                                                                          

docs/explanation/flowcharts/backups.md

@@ -71,7 +71,6 @@ flowchart TD
 ```
 
 ## On `list-backups` hook
-[Click to navigate the mermaid diagram on GitHub](https://github.com/canonical/postgresql-k8s-operator/blob/main/docs/explanation/e-backups.md).
 
 ```{mermaid}
 flowchart TD
@@ -85,7 +84,6 @@ flowchart TD
 ```
 
 ## On `restore` hook
-[Click to navigate the mermaid diagram on GitHub](https://github.com/canonical/postgresql-k8s-operator/blob/main/docs/explanation/e-backups.md).
 
 ```{mermaid}
 flowchart TD

docs/explanation/interfaces-and-endpoints.md

@@ -39,7 +39,7 @@ Find all details about default and extra DB user roles in [](/explanation/users)
 ```{note}
 Legacy relations are deprecated and will be discontinued on future releases. Their usage should be avoided. 
 
-Check the legacy interfaces implementation limitations in [](/explanation/legacy-charm)"
+Check the limitations of legacy interface implementations in [](/explanation/legacy-charm)
 ```
 
 ### Legacy `pgsql` interface (`db` and `db-admin` endpoints):

docs/explanation/juju.md

@@ -26,7 +26,7 @@ In the context of this documentation, the pertinent changes are as follows:
 |`run`|`exec`|
 |`run-action --wait`|`run`|
 
-See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#juju-3-0-0---22-oct-2022) for the comprehensive list of changes.
+See the [Juju 3.0 release notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022) for the comprehensive list of changes.
 
 Example substitutions:
 

docs/explanation/legacy-charm.md

@@ -1,11 +1,11 @@
 # Legacy charm
 
-There are [two types of charms](https://juju.is/docs/sdk/charm-taxonomy#charm-types-by-generation) stored under the same charm name `postgresql-k8s`:
+There are [two types of charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) stored under the same charm name `postgresql-k8s`:
 
-1. [Reactive](https://juju.is/docs/sdk/charm-taxonomy#reactive)  charm in the channel `latest/stable` (called `legacy`)
-2. [Ops-based](https://juju.is/docs/sdk/ops) charm in the channel `14/stable` (called `modern`)
+1. [Reactive](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive)  charm in the channel `latest/stable` (called `legacy`)
+2. [Ops-based](https://documentation.ubuntu.com/juju/3.6/reference/charm/#ops) charm in the channel `14/stable` (called `modern`)
 
-The legacy charm provided endpoints `db` and `db-admin` (for the interface `pgsql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `postgresql_client`). Read more details about the available [endpoints/interfaces](https://charmhub.io/postgresql-k8s/docs/e-interfaces).
+The legacy charm provided endpoints `db` and `db-admin` (for the interface `pgsql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `postgresql_client`). Read more details about the available [endpoints/interfaces](/explanation/interfaces-and-endpoints).
 
 ```{note}
 Choose one endpoint to use, rather than relating both simultaneously.
@@ -39,7 +39,7 @@ Note that the `trust` option must be enabled if [Role Based Access Control (RBAC
 
 Reactive charms cannot be upgraded to an operator-framework-based version. To move database data, the new DB application must be launched nearby, and data should be copied from "legacy" application to the "modern" one. 
 
-Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need migration instructions.
+Please [contact us](/reference/contacts) if you need migration instructions.
 ```
 
 ## How to deploy old "legacy" postgresql charm
@@ -62,7 +62,7 @@ A common error message is: `cannot deploy application "postgresql": unknown opti
 
 ## Config options supported by modern charm
 
-The legacy charm config options were not moved to the modern charm due to no need. The modern charm applies the best possible configuration automatically. Feel free to [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) about the DB tuning/config options.
+The legacy charm configuration options were not moved to the modern charm due to no need. The modern charm applies the best possible configuration automatically. Feel free to [contact us](/reference/contacts) about the DB tuning/config options.
 
 ## Extensions supported by modern charm
 
@@ -77,7 +77,7 @@ In the legacy charm, the user could request roles by setting the `roles` field t
 ## Supported PostgreSQL versions by modern charm
 
 At the moment, the modern charms support PostgreSQL 14 (based on Jammy/22.04 series) only.
-Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need different versions/series.
+Please [contact us](/reference/contacts) if you need different versions/series.
 
 ## Supported architectures: amd64, arm64, ...
 Currently, the charm supports architecture `amd64` (all revisions) and `arm64` (from revision 211+). 
@@ -90,5 +90,4 @@ The "legacy charm" (from `latest/stable`) is stored on [Launchpad](https://git.l
 
 The "modern charm" (from `14/stable`) is stored on [GitHub](https://github.com/canonical/postgresql-k8s-operator), here is the link to report [modern charm issues](https://github.com/canonical/postgresql-k8s-operator/issues/new/choose).
 
-Do you have questions? [Contact us](https://chat.charmhub.io/charmhub/channels/data-platform)!
-
+Do you have questions? [Contact us](/reference/contacts)!

docs/explanation/logs.md

@@ -1,6 +1,6 @@
 # Logs
 
-This page summarizes all log types in Charmed PostgreSQL to simplify troubleshooting.
+This page summarises all log types in Charmed PostgreSQL to simplify troubleshooting.
 
 For an overview of all charm components, see [](/explanation/architecture).
 
@@ -96,5 +96,5 @@ Charmed PostgreSQL is configured to rotate PostgreSQL text logs every minute and
 
 For PostgreSQL, logs will be truncated when the week turns and the same minute of the same hour of the same weekday comes to pass. E.g. at 12:01 UTC on Monday either a new log file will be created or last week's log will be overwritten.
 
-Due to Patroni only supporting size based rotation, it has been configured to retain logs for a comparatively similar timeframe as PostgreSQL. The assumed size of a minute of Patroni logs is 600 bytes, but the estimation is bound to be imprecise. Patroni will retain 10,080 log files (for every minute of a week). The current log is `patroni.log`, when rotating Patroni will append a number to the name of the file and remove logs over the limit.
+Due to Patroni only supporting size based rotation, it has been configured to retain logs for a comparatively similar time frame as PostgreSQL. The assumed size of a minute of Patroni logs is 600 bytes, but the estimation is bound to be imprecise. Patroni will retain 10,080 log files (for every minute of a week). The current log is `patroni.log`, when rotating Patroni will append a number to the name of the file and remove logs over the limit.