docs: Update Starter Pack

.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/check-removed-urls.yml

@@ -0,0 +1,56 @@
+name: Check for removed URLs
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v5
+        with:
+          # This implicitly gets the PR branch. Making it explicit causes problems
+          # with private forks, but it is equivalent to the following:
+          # repository: ${{ github.event.pull_request.head.repo.full_name }}
+          # ref: ${{ github.event.pull_request.head.ref }}
+          fetch-depth: 0
+          path: compare
+      - name: Checkout base branch
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+          repository: ${{ github.event.pull_request.base.repo.full_name }}
+          fetch-depth: 0
+          path: base
+      - uses: actions/setup-python@v6
+      - name: Build docs
+        run: |
+          for dir in compare base; do
+            pushd ${dir}/docs
+            make install
+            . .sphinx/venv/bin/activate
+            make html
+            popd
+          done
+      - name: Generate current URLs list
+        run: |
+          for dir in compare base; do
+            pushd ${dir}/docs
+            find ./_build/ -name '*.html' \
+            | sed 's|/_build||;s|/index.html$|/|;s|.html$||' \
+            | sort > urls.txt
+            popd
+          done
+      - name: Compare URLs
+        run: |
+          BASE_URLS_PATH="base/docs/urls.txt"
+          COMPARE_URLS_PATH="compare/docs/urls.txt"
+          removed=$(comm -23 ${BASE_URLS_PATH} ${COMPARE_URLS_PATH} )
+          if [ -n "$removed" ]; then
+            echo "The following URLs were removed:"
+            echo "$removed"
+            echo "Please ensure removed pages are redirected"
+            exit 1
+          fi

.github/workflows/cla-check.yml

@@ -0,0 +1,13 @@
+# This workflow checks if the contributor has signed the Canonical Contributor Licence Agreement (CLA)
+name: Canonical Contributor Licence Agreement check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  cla-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if CLA signed
+        uses: canonical/has-signed-canonical-cla@v2

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

@@ -0,0 +1,27 @@
+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@v5
+      with:
+        fetch-depth: 0
+    - name: Create venv
+      working-directory: "docs"
+      run: make install
+    - name: Lint markdown
+      working-directory: "docs"
+      run: make lint-md

.readthedocs.yaml

@@ -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/main -- '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

docs/.gitignore

@@ -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/

docs/.sphinx/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: make-spelling
+        name: Run make spelling
+        entry: make -C docs spelling
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-linkcheck
+        name: Run make linkcheck
+        entry: make -C docs linkcheck
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-woke
+        name: Run make woke
+        entry: make -C docs woke
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$

docs/.sphinx/.pymarkdown.json

@@ -0,0 +1,46 @@
+{
+    "plugins": {
+        "selectively_enable_rules": true,
+        "heading-style": {
+            "enabled": true,
+            "style": "atx"
+        },
+        "commands-show-output": {
+            "enabled": true
+        },
+        "no-missing-space-atx": {
+            "enabled": true
+        },
+        "blanks-around-headings": {
+            "enabled": true
+        },
+        "heading-start-left": {
+            "enabled": true
+        },
+        "no-trailing-punctuation": {
+            "enabled": true,
+            "punctuation": ".,;。，；"
+        },
+        "blanks-around-fences": {
+            "enabled": true,
+            "list_items": false
+        },
+        "blanks-around-lists": {
+            "enabled": true
+        },
+        "hr-style": {
+            "enabled": true
+        },
+        "no-empty-links": {
+            "enabled": true
+        },
+        "no-alt-text": {
+            "enabled": true
+        }
+    },
+    "extensions": {
+        "front-matter" : {
+            "enabled" : true
+        }
+    }
+}