Refactor v14 documentation for Sphinx (#981)

* 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

Author: a-velasco

.github/workflows/automatic-doc-checks.yml

@@ -0,0 +1,24 @@
+#
+name: Automatic doc checks
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    paths:
+      - 'docs/**'   # Only run on changes to the docs directory
+
+  workflow_dispatch:
+    # Manual trigger
+
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: "docs"
+      fetch-depth: 0

.github/workflows/ci.yaml

@@ -14,7 +14,7 @@ on:
       - 'LICENSE'
       - '**.md'
       - .github/renovate.json5
-      - '.github/workflows/sync_docs.yaml'
+      - 'docs/**'
   schedule:
     - cron: '53 0 * * *'  # Daily at 00:53 UTC
   # Triggered on push to branch "main" by .github/workflows/release.yaml

.github/workflows/lib-check.yaml

@@ -14,6 +14,7 @@ on:
       - 'LICENSE'
       - '**.md'
       - 'renovate.json'
+      - 'docs/**'
 
 jobs:
   lib-check:

.github/workflows/markdown-style-checks.yml

@@ -0,0 +1,24 @@
+name: Markdown style checks
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - 'docs/**'   # Only run on changes to the docs directory
+  pull_request:
+    branches:
+    - '*'
+    paths:
+    - 'docs/**'   # Only run on changes to the docs directory
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: DavidAnson/markdownlint-cli2-action@v16
+      with:
+        config: "docs/.sphinx/.markdownlint.json"

.github/workflows/sync_docs.yaml

@@ -6,7 +6,7 @@ build/
 coverage.xml
 __pycache__/
 *.py[cod]
-requirements.txt
+./requirements.txt
 requirements-last-build.txt
 
 # PyCharm project folder.

.gitignore

@@ -0,0 +1,39 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_checkout:
+    - git fetch --unshallow || true
+    # Cancel building pull requests when there aren't changed in the docs directory.
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/14/docs -- 'docs/' '.readthedocs.yaml';
+      then
+        exit 183;
+      fi
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+# - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/requirements.txt

.readthedocs.yaml

@@ -1,22 +1,21 @@
 # Charmed PostgreSQL K8s operator
+
 [![CharmHub Badge](https://charmhub.io/postgresql-k8s/badge.svg)](https://charmhub.io/postgresql-k8s)
 [![Release](https://github.com/canonical/postgresql-k8s-operator/actions/workflows/release.yaml/badge.svg)](https://github.com/canonical/postgresql-k8s-operator/actions/workflows/release.yaml)
 [![Tests](https://github.com/canonical/postgresql-k8s-operator/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/canonical/postgresql-k8s-operator/actions/workflows/ci.yaml?query=branch%3Amain)
 [![codecov](https://codecov.io/gh/canonical/postgresql-k8s-operator/graph/badge.svg?token=KmBJqV1AM2)](https://codecov.io/gh/canonical/postgresql-k8s-operator)
 
-## Description
-
-This repository contains a [Juju Charm](https://charmhub.io/postgresql-k8s) for deploying [PostgreSQL](https://www.postgresql.org/about/) on Kubernetes.
+This repository contains a charmed operator for deploying [PostgreSQL](https://www.postgresql.org/about/) on Kubernetes via the [Juju orchestration engine](https://juju.is/).
 
-To deploy on virtual machines, please use [Charmed PostgreSQL operator](https://charmhub.io/postgresql).
+To learn more about how to deploy and operate Charmed PostgreSQL K8s, see the [official documentation](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/).
 
 ## Usage
 
-Bootstrap a Kubernetes (e.g. [Multipass-based MicroK8s](https://discourse.charmhub.io/t/charmed-environment-charm-dev-with-canonical-multipass/8886)) and create a new model using Juju 2.9+:
+Bootstrap a Kubernetes (e.g. [Multipass-based MicroK8s](https://discourse.charmhub.io/t/charmed-environment-charm-dev-with-canonical-multipass/8886)) and create a new model using Juju 3.6+:
 
 ```shell
 juju add-model postgresql-k8s
-juju deploy postgresql-k8s --channel 14 --trust
+juju deploy postgresql-k8s --channel 14/stable --trust
 ```
 
 **Note:** the `--trust` flag is required because the charm and Patroni need to create some K8s resources.
@@ -62,7 +61,7 @@ Adding a relation is accomplished with `juju relate` (or `juju integrate` for Ju
 
 ```shell
 # Deploy Charmed PostgreSQL cluster with 3 nodes
-juju deploy postgresql-k8s -n 3 --trust --channel 14
+juju deploy postgresql-k8s --channel 14/stable -n 3 --trust --channel 14
 
 # Deploy the relevant application charms
 juju deploy mycharm
@@ -87,7 +86,7 @@ juju status --relations
 This charm supports legacy interface `pgsql` from the previous [PostgreSQL charm](https://launchpad.net/postgresql-charm):
 
 ```shell
-juju deploy postgresql-k8s --trust --channel 14
+juju deploy postgresql-k8s --channel 14/stable --trust 
 juju deploy finos-waltz-k8s --channel edge
 juju relate postgresql-k8s:db finos-waltz-k8s
 ```

README.md

@@ -0,0 +1,40 @@
+# Leave a blank line at the end of this file to support concatenation
+backend
+backends
+Charmcraft
+cjk
+cryptographically
+dvipng
+fonts
+freefont
+github
+GPG
+gyre
+https
+Intersphinx
+lang
+LaTeX
+latexmk
+Multipass
+otf
+plantuml
+PNG
+Pygments
+QEMU
+Rockcraft
+rst
+SVG
+tex
+texlive
+TOC
+toctree
+txt
+uncommenting
+utils
+VMs
+WCAG
+whitespace
+whitespaces
+wordlist
+xetex
+xindy

docs/.custom_wordlist.txt

@@ -0,0 +1,26 @@
+# Environment
+*env*/
+.sphinx/venv/
+
+# Sphinx
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
+.sphinx/update/
+.sphinx/node_modules/
+
+# Vale
+.sphinx/styles/*
+.sphinx/vale.ini
+
+# Build outputs
+_build
+
+# Node.js
+package*.json
+
+# Unrelated cache and config files
+.DS_Store
+__pycache__
+.idea/
+.vscode/