Fix broken URLs and spelling errors (#993)

* add starter pack and sync tutorial with VM

* update deployment guides

* rename how-to-guides to how-to

* sync how-to guides with vm

* sync references with vm

* sync explanation pages with vm

* add .readthedocs.yaml and reduce .gitignore scope for requirements.txt file

* fix some formatting issues

* sync backup guides with vm

* fix misc. build errors and sync tutorial with vm

* add doc ci checks

* remove discourse sync workflow

* polish tutorial and deploy guide

* specify channel on all deploy commands

* sync misc. pages with vm

* minor README update with new documentation link

* ignore docs folder in development workflows

* remove sphinx python dependency check workflow

* update home page

* fix some broken links

* fix broken links

* fix spelling errors in docs

* fix spelling errors in other markdown files

* small spelling fix

Author: a-velasco

.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,10 +11,10 @@ labels: bug
 <!-- Please enable debug logging by running `juju model-config logging-config="<root>=INFO;unit=DEBUG"` (if possible) -->
 1. 
 
-## Expected behavior
+## Expected behaviour
 
 
-## Actual behavior
+## Actual behaviour
 <!-- If applicable, add screenshots -->
 
 

CONTRIBUTING.md

@@ -8,9 +8,9 @@ this operator.
 - Generally, before developing enhancements to this charm, you should consider [opening an issue
   ](https://github.com/canonical/postgresql-k8s-operator/issues) explaining your use case.
 - If you would like to chat with us about your use-cases or proposed implementation, you can reach
-  us at [public Canonical Data Platform channel](https://chat.charmhub.io/charmhub/channels/data-platform)
+  us at [our public Mattermost channel](https://matrix.to/#/#charmhub-data-platform:ubuntu.com)
   or [Discourse](https://discourse.charmhub.io/).
-- Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library
+- Familiarising yourself with the [Charmed Operator Framework](https://ops.readthedocs.io/en/latest/index.html) library
   will help you a lot when working on new features or bug fixes.
 - All enhancements require review before being merged. Code review typically examines
   - code quality

README.md

@@ -104,7 +104,7 @@ For more information, see the [Security policy](SECURITY.md).
 
 ## Contributing
 
-Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhancements to this charm following best practice guidelines, and [CONTRIBUTING.md](https://github.com/canonical/postgresql-k8s-operator/blob/main/CONTRIBUTING.md) for developer guidance.
+Please see the [Juju SDK docs](https://documentation.ubuntu.com/juju/3.6/) for guidelines on enhancements to this charm following best practice guidelines, and [CONTRIBUTING.md](https://github.com/canonical/postgresql-k8s-operator/blob/main/CONTRIBUTING.md) for developer guidance.
 
 ## License
 

SECURITY.md

@@ -3,7 +3,7 @@
 ## What qualifies as a security issue
 
 Credentials leakage, outdated dependencies with known vulnerabilities, and
-other issues that could lead to unprivileged or unauthorized access to the
+other issues that could lead to unprivileged or unauthorised access to the
 database or the system.
 
 ## Reporting a vulnerability

docs/.custom_wordlist.txt

@@ -1,40 +1,138 @@
 # Leave a blank line at the end of this file to support concatenation
+airgap
+analyze
+artifact
+Artifactory
+artifacts
+async
+aws
+AWS
+AZ
+AZs
 backend
 backends
+balancer
+balancers
+benchmark
+benchmarking
+CharmBase
 Charmcraft
+charmhub
+checksum
+checksums
+CIS
 cjk
+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
 lang
 LaTeX
 latexmk
+LDAP
+libs
+lifecycle
+MinIO
 Multipass
+nameserver
+nameservers
+Nextcloud
 otf
+Parca
+Patroni
+Patroni*
+pgbackrest
+pgBackRest
+pgbouncer
+Pgbouncer*
+pgsql
+PITR
 plantuml
 PNG
+pooler
+postgres
+postgresql
+pqsql
+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
+PPA
+PPAs
+programmatically
+codebase
+Juju's

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/connection-pooling.md

@@ -8,7 +8,7 @@ A way to achieve this with Charmed PostgreSQL K8s is by integrating with the [Pg
 
 ## Increasing maximum allowed connections
 
-If using PgBouncer is not enough to handle the connections load of your application, you can increase the amount of connections that PostgreSQL can open via the [`experimental_max_connections` config parameter](https://charmhub.io/postgresql-k8s/configurations#experimental_max_connections). 
+If using PgBouncer is not enough to handle the connections load of your application, you can increase the amount of connections that PostgreSQL can open via the [`experimental_max_connections` configuration parameter](https://charmhub.io/postgresql-k8s/configurations#experimental_max_connections). 
 
 ```{caution}
 Each connection opened by PostgreSQL spawns a new process, which is resource-intensive. Use this option as a last resort.

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/flowcharts/relations.md

@@ -1,6 +1,6 @@
 # Relations flowcharts
 
-This reference documentation details the implementation of the `database-peers` peer relation. This is the peer relation for PostgreSQL, used to share user and config information from the leader unit to the follower units. The file implementing these relations can be found here: [src/relations/charm.py](https://github.com/canonical/postgresql-k8s-operator/blob/main/src/charm.py) (it should be moved to a file called `src/relations/peers.py` in the future).
+This reference documentation details the implementation of the `database-peers` peer relation. This is the peer relation for PostgreSQL, used to share user and configuration information from the leader unit to the follower units. The file implementing these relations can be found here: [src/relations/charm.py](https://github.com/canonical/postgresql-k8s-operator/blob/main/src/charm.py) (it should be moved to a file called `src/relations/peers.py` in the future).
 
 ## Expected interface
 

docs/explanation/juju.md

@@ -2,7 +2,7 @@
 
 [Juju](https://juju.is/) is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure using charms.
 
-> See also: [Juju client documentation](https://juju.is/docs/juju), [Juju blog](https://ubuntu.com/blog/tag/juju)
+> See also: {{juju_documentation_url}}, [Juju blog](https://ubuntu.com/blog/tag/juju)
 
 ## Compatibility with PostgreSQL
 
@@ -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://juju.is/docs/juju/roadmap) for the comprehensive list of changes.
 
 Example substitutions: