Fix automatic doc checks (16) (#1034)

* feat: add rediraffe sphinx extension and discourse redirects for each page

* fix broken urls and update custom wordlist

* fix spelling errors

* polish explanation landing page and toctree

Author: a-velasco

docs/.custom_wordlist.txt

@@ -1,40 +1,154 @@
+
 # 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
+backport
+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
+IPs
+IPv
+Jira
+jitter
+Juju
+Juju's
 lang
 LaTeX
 latexmk
+LDAP
+libs
+lifecycle
+LXD
+LXD's
+MicroK8s
+MinIO
 Multipass
+nameserver
+nameservers
+Nextcloud
 otf
+Parca
+Parca's
+Patroni
+patronictl
+pgbackrest
+pgBackRest
+pgbouncer
+pgsql
+PITR
 plantuml
 PNG
+pooler
+postgres
+postgresql
+PPA
+PPAs
+pqsql
+programmatically
+PSC
+PVCs
+py
 Pygments
 QEMU
+RadosGW
+requirer
+rockcraft
 Rockcraft
+routable
 rst
+scalable
+sdk
+SHA
+snap
+snapcraft
+SoS
+squashfs
+SquashFS
+src
+SSL
+stateful
+subnet
 SVG
+Sysbench
+terraform
 tex
 texlive
+TimescaleDB
 TOC
 toctree
+Traefik
 txt
+ubuntu
 uncommenting
+uncordon
 utils
+vm
 VMs
+WAL
+walkthrough
 WCAG
+wget
 whitespace
 whitespaces
+WIP
 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

@@ -208,7 +208,8 @@
 linkcheck_ignore = [
     "http://127.0.0.1:8000",
     "https://github.com/canonical/ACME/*",
-    "https://matrix.to/*"
+    "https://matrix.to/*",
+    "https://portal.azure.com/#browse/Microsoft.Compute/VirtualMachines"
     ]
 
 # A regex list of URLs where anchors are ignored by 'make linkcheck'

docs/explanation/architecture.md

@@ -4,7 +4,6 @@
 
 ![image|690x423, 100%](architecture-diagram.png)
 
-<a name="hld"></a>
 ## HLD (High Level Design)
 
 The charm design leverages on the SNAP “[charmed-postgresql](https://snapcraft.io/charmed-postgresql)” which is deployed by Juju on the specified VM/MAAS/bare-metal machine based on Ubuntu Jammy/22.04. SNAP allows to run PostgreSQL service(s) in a secure and isolated environment ([strict confinement](https://ubuntu.com/blog/demystifying-snap-confinement)). The installed SNAP:
@@ -56,7 +55,6 @@ The snap "charmed-postgresql" also ships list of tools used by charm:
 All snap resources must be executed under the special snap user `_daemon_` only!
 ```
 
-<a name="integrations"></a>
 ## Integrations
 
 ### PgBouncer
@@ -85,7 +83,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
 
@@ -97,7 +95,7 @@ Prometheus is an open-source systems monitoring and alerting toolkit with a dime
 
 ## LLD (Low Level Design)
 
-Please check the charm state machines displayed in the [workflow diagrams](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/14/explanation/flowcharts/). The low-level logic is mostly common for both VM and K8s charms.
+Please check the charm state machines displayed in the [workflow diagrams](https://discourse.charmhub.io/t/charmed-postgresql-k8s-explanations-charm-flowcharts/9305). The low-level logic is mostly common for both VM and K8s charms.
 
 <!--- TODO: Describe all possible installations? Cross-model/controller? --->
 
@@ -107,25 +105,26 @@ Accordingly to the [Juju SDK](https://juju.is/docs/sdk/event): “an event is a
 
 For this charm, the following events are observed:
 
-1. [`on_install`](https://juju.is/docs/sdk/install-event): install the snap "charmed-postgresql" and perform 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.
-3. [`leader-settings-changed`](https://juju.is/docs/sdk/leader-settings-changed-event): Handle the leader settings changed event.
-4. [`start`](https://juju.is/docs/sdk/start-event): Init/setting up the cluster node.
-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. [`on_install`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#install): install the snap "charmed-postgresql" and perform 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.
+3. [`leader-settings-changed`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#leader-settings-changed): Handle the leader settings changed event.
+4. [`start`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#start): Init/setting up the cluster node.
+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?
+1. TODO: any other events?
 --->
 
 ### Charm code overview
 
-[`src/charm.py`](https://github.com/canonical/postgresql-operator/blob/main/src/charm.py) is the default entry point for a charm and has the `PostgresqlOperatorCharm` Python class which inherits from CharmBase.
+[`src/charm.py`](https://github.com/canonical/postgresql-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/) (Python framework for developing charms). See more information in the [Ops documentation for `CharmBase`](https://ops.readthedocs.io/en/latest/reference/ops.html#ops.CharmBase).
 
 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!):
+
 ```text
 > charmcraft list-lib postgresql-k8s                                                                                                                                                                                                               
 Library name    API    Patch                                                                                                                                                                                                                          

docs/explanation/index.md

@@ -1,48 +1,33 @@
 # Explanation
 
-This section contains pages with more detailed explanations that provide additional context about key concepts behind the PostgreSQL charm.
+Additional context about key concepts behind the PostgreSQL charm, including design and legacy information.
 
 ## Core concepts and design
-* [Architecture]
-* [Interfaces and endpoints]
-* [Legacy charm]
-
-## Operational concepts
-* [Units]
-* [Users]
-* [Logs]
-* [Connection pooling]
-
-## Security and hardening
-* [Security hardening guide][Security]
-  * [Cryptography]
-
-
-<!-- Links -->
-
-[Architecture]: /explanation/architecture
-[Interfaces and endpoints]: /explanation/interfaces-and-endpoints
-[Units]: /explanation/units
-[Users]: /explanation/users
-[Logs]: /explanation/logs
-[Legacy charm]: /explanation/legacy-charm
-[Connection pooling]: /explanation/connection-pooling
-[Security]: /explanation/security/index
-[Cryptography]: /explanation/security/cryptography
-
 
 ```{toctree}
 :titlesonly:
-:maxdepth: 2
-:glob:
-:hidden:
 
 Architecture <architecture>
 Interfaces and endpoints <interfaces-and-endpoints>
 Legacy charm <legacy-charm>
+```
+
+## Operational concepts
+
+```{toctree}
+:titlesonly:
+
 Units <units>
 Users <users>
 Roles <roles>
 Logs <logs>
 Connection pooling <connection-pooling>
-Security <security/index>
+```
+
+## Security and hardening
+
+```{toctree}
+:titlesonly:
+
+Security <security/index>
+```

docs/explanation/legacy-charm.md

@@ -1,19 +1,19 @@
-# Charm types: "legacy" vs "modern"
+# 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`:
+There are [two types of charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) stored under the same charm name `postgresql`:
 
-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 channels `14/stable` and `16/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](/explanation/interfaces-and-endpoints).
 
 ```{note}
 Choose one endpoint to use, rather than relating both simultaneously.
 ```
 
-<!--TODO: Explain `latest` in the context of `16`-->
+<!--TODO: Explain in the context of 16 -->
 
-## The default track `latest` vs `14`
+## The default track "latest" vs "14"
 
 The [default track](https://docs.openstack.org/charm-guide/yoga/project/charm-delivery.html) has been switched from the `latest` to `14`. It is [to ensure](https://discourse.charmhub.io/t/request-switch-default-track-from-latest-to-14-for-postgresql-k8s-charms/10314) all new deployments use a modern codebase. We strongly advise against using the latest track due to its implicit nature. In doing so, a future charm upgrade may result in a PostgreSQL version incompatible with an integrated application. Track 14 guarantees PostgreSQL 14 deployment only. The track `latest` will be closed after all applications migrated from Reactive to Ops-based charm.
 
@@ -31,12 +31,13 @@ The "modern" charm provides temporary support for the legacy interfaces:
 
 * **proper migration**: migrate the application to the new interface "[postgresql_client](https://github.com/canonical/charm-relation-interfaces)". The application will connect PostgreSQL using "[data_interfaces](https://charmhub.io/data-platform-libs/libraries/data_interfaces)" library from "[data-platform-libs](https://github.com/canonical/data-platform-libs/)" via endpoint `database`.
 
+
 ```{warning}
 **In-place upgrades are not supported for this case.**
 
 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
@@ -49,7 +50,7 @@ Deploy the charm using the channel `latest/stable`:
     channel: latest/stable
 ```
 
-```{note}
+```{caution}
 Remove the charm store prefix `cs:` from the bundle. 
 
 Otherwise, the modern charm will be chosen by Juju (due to the default track pointing to `14/stable` and not `latest/stable`).
@@ -61,7 +62,7 @@ A common error message is: `cannot deploy application "postgresql": unknown opti
 
 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.
+Feel free to [contact us](/reference/contacts) about the DB tuning/config options.
 
 ## Extensions supported by modern charm
 
@@ -81,7 +82,7 @@ For more information about migrating the new interface, see [this guide](/how-to
 
 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
 

docs/explanation/logs.md

@@ -98,5 +98,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.