docs: use Canonical documentation starter pack

.github/workflows/docs.yaml

@@ -0,0 +1,49 @@
+#
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_call:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docchecks:
+    name: Checks
+    runs-on: ubuntu-22.04
+    outputs:
+      spellcheck-result: ${{ steps.spellcheck-step.outcome }}
+      linkcheck-result: ${{ steps.linkcheck-step.outcome }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Spelling
+        id: spellcheck-step
+        if: success() || failure()
+        uses: canonical/documentation-workflows/spellcheck@main
+        with:
+          working-directory: docs
+      - name: Links
+        id: linkcheck-step
+        if: success() || failure()
+        uses: canonical/documentation-workflows/linkcheck@main
+        with:
+          working-directory: docs
+      - name: Markdown lint
+        id: markdown-step
+        if: success() || failure()
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          config: "docs/.sphinx/.markdownlint.json"        

.readthedocs.yaml

@@ -1,13 +1,26 @@
-version: "2"
+# .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-24.04"
+  os: ubuntu-22.04
   tools:
     python: "3.12"
+  jobs:
+    pre_install:
+    - git fetch --unshallow || true
 
-python:
-  install:
-    - requirements: docs/requirements.txt
-
+# Build documentation in the docs/ directory with Sphinx
 sphinx:
+  builder: dirhtml
   configuration: docs/conf.py
+  fail_on_warning: true
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/.sphinx/requirements.txt

Makefile

@@ -11,8 +11,7 @@ all: format lint static unit
 # Build documentation
 .PHONY: docs
 docs:
-	uv export --group docs >docs/requirements.txt
-	uv run --group docs sphinx-build docs/ docs/_build/html
+	$(MAKE) -C docs run
 
 # Fix linting issues
 .PHONY: fix

docs/.custom_wordlist.txt

@@ -0,0 +1,7 @@
+# Leave a blank line at the end of this file to support concatenation
+args
+config
+Pythonic
+stdout
+stderr
+URI

docs/.gitignore

@@ -0,0 +1,25 @@
+# Environment
+*env*/
+.sphinx/venv/
+
+# Sphinx
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
+.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/

docs/.sphinx/.markdownlint.json

@@ -0,0 +1,21 @@
+{
+    "default": false,
+    "MD003": {
+        "style": "atx"
+    },
+    "MD014": true,
+    "MD018": true,
+    "MD022": true,
+    "MD023": true,
+    "MD026": {
+        "punctuation": ".,;。，；"
+    },
+    "MD031": {
+        "list_items": false
+    },
+    "MD032": true,
+    "MD035": true,
+    "MD042": true,
+    "MD045": true,
+    "MD052": true
+}

docs/.sphinx/.wordlist.txt

@@ -0,0 +1,64 @@
+ACME
+ACME's
+addons
+AGPLv
+API
+APIs
+balancer
+Charmhub
+CLI
+DCO
+Diátaxis
+Dqlite
+dropdown
+EBS
+EKS
+enablement
+favicon
+Furo
+Git
+GitHub
+Grafana
+IAM
+installable
+JSON
+Juju
+Kubeflow
+Kubernetes
+Launchpad
+linter
+LTS
+LXD
+Makefile
+Makefiles
+Matrix
+Mattermost
+MicroCeph
+MicroCloud
+MicroOVN
+MyST
+namespace
+namespaces
+NodePort
+Numbat
+observability
+OEM
+OLM
+Permalink
+pre
+Quickstart
+ReadMe
+reST
+reStructuredText
+roadmap
+RTD
+subdirectories
+subfolders
+subtree
+TODO
+Ubuntu
+UI
+UUID
+VM
+webhook
+YAML

docs/.sphinx/get_vale_conf.py

@@ -0,0 +1,53 @@
+#! /usr/bin/env python
+
+import requests
+import os
+
+DIR = os.getcwd()
+
+
+def main():
+    if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"):
+        print("Vale directory exists")
+    else:
+        os.makedirs(f"{DIR}/.sphinx/styles/Canonical")
+
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/Canonical"
+    )
+    r = requests.get(url)
+    for item in r.json():
+        download = requests.get(item["download_url"])
+        file = open(".sphinx/styles/Canonical/" + item["name"], "w")
+        file.write(download.text)
+        file.close()
+
+    if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"):
+        print("Vocab directory exists")
+    else:
+        os.makedirs(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical")
+
+    url = (
+        "https://api.github.com/repos/canonical/praecepta/"
+        + "contents/styles/config/vocabularies/Canonical"
+    )
+    r = requests.get(url)
+    for item in r.json():
+        download = requests.get(item["download_url"])
+        file = open(
+            ".sphinx/styles/config/vocabularies/Canonical/" + item["name"],
+            "w"
+        )
+        file.write(download.text)
+        file.close()
+    config = requests.get(
+        "https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini"
+    )
+    file = open(".sphinx/vale.ini", "w")
+    file.write(config.text)
+    file.close()
+
+
+if __name__ == "__main__":
+    main()

docs/.sphinx/metrics/build_metrics.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# shellcheck disable=all
+
+links=0
+images=0
+
+# count number of links
+links=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<a " | wc -l)
+# count number of images
+images=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<img " | wc -l)
+
+# summarise latest metrics
+echo "Summarising metrics for build files (.html)..."
+echo -e "\tlinks: $links"
+echo -e "\timages: $images"

docs/.sphinx/metrics/source_metrics.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# shellcheck disable=all
+
+VENV=".sphinx/venv/bin/activate"
+
+files=0
+words=0
+readabilityWords=0
+readabilitySentences=0
+readabilitySyllables=0
+readabilityAverage=0
+readable=true
+
+# measure number of files (.rst and .md), excluding those in .sphinx dir
+files=$(find . -type d -path './.sphinx' -prune -o -type f \( -name '*.md' -o -name '*.rst' \) -print | wc -l)
+
+# calculate metrics only if source files are present
+if [ "$files" -eq 0 ]; then
+    echo "There are no source files to calculate metrics"
+else
+    # measure raw total number of words, excluding those in .sphinx dir
+    words=$(find . -type d -path './.sphinx' -prune -o \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w)
+
+    # calculate readability for markdown source files
+    echo "Activating virtual environment to run vale..."
+    source "${VENV}"
+
+    for file in *.md *.rst; do
+        if [ -f "$file" ]; then
+            readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g')
+            readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g')
+            readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g')
+        fi
+    done
+
+    echo "Deactivating virtual environment..."
+    deactivate
+
+    # calculate mean number of words
+    if [ "$files" -ge 1 ]; then
+        meanval=$((readabilityWords / files))
+    else
+        meanval=$readabilityWords
+    fi
+
+    readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc)
+
+    # cast average to int for comparison
+    readabilityAverageInt=$(echo "$readabilityAverage / 1" | bc)
+
+    # value below 8 is considered readable
+    if [ "$readabilityAverageInt" -lt 8 ]; then
+        readable=true
+    else
+        readable=false
+    fi
+
+    # summarise latest metrics
+    echo "Summarising metrics for source files (.md, .rst)..."
+    echo -e "\ttotal files: $files"
+    echo -e "\ttotal words (raw): $words"
+    echo -e "\ttotal words (prose): $readabilityWords"
+    echo -e "\taverage word count: $meanval"
+    echo -e "\treadability: $readabilityAverage"
+    echo -e "\treadable: $readable"
+fi

docs/.sphinx/pa11y.json

@@ -0,0 +1,9 @@
+{
+  "chromeLaunchConfig": {
+    "args": [
+      "--no-sandbox"
+    ]
+  },
+  "reporter": "cli",
+  "standard": "WCAG2AA"
+}

docs/.sphinx/requirements.txt

@@ -0,0 +1,4 @@
+canonical-sphinx[full]
+sphinx-autobuild
+sphinxcontrib-svg2pdfconverter[CairoSVG]
+sphinx-last-updated-by-git