Docs: migrate Sphinx docs starter-pack to latest extension (infra) (#2054)

* Migrate docs starter-pack to extension version 1.2.0

The starter-pack has been upgraded to the extension-based version:
more tooling supports are provided and most styling configurations are
centralized in the canonical-sphinx extension.
This upgrade uses the extension v5.1.0, and the starter-pack
1.2.0
https://github.com/canonical/sphinx-docs-starter-pack/releases/tag/1.2.0

* Update Makefile to the latest version

* update conf.py to latest and clean up requirements

* update spelling wordlist and doc fix

* add release version to title

* black formatting

* update doc check workflow to use new tooling

* build readthedocs only upon docs changes

* remove unused docs scripts: metrics and update

Author: tang-mm

.github/workflows/documentation-check.yml

@@ -31,11 +31,6 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Install Aspell
-        run: |
-          sudo apt update -qq
-          sudo apt install -qq -y aspell aspell-en
-
       - name: Install the doc framework
         working-directory: docs/
         run: |
@@ -63,13 +58,16 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: woke
-        uses: get-woke/woke-action@b2ec032c4a2c912142b38a6a453ad62017813ed0
-        with:
-          # Cause the check to fail on any broke rules
-          fail-on-error: true
-          workdir: docs/
-          woke-args: "*.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml"
+      - name: Install the doc framework
+        working-directory: docs/
+        run: |
+          sudo apt install -y -qq python3-venv
+          make install
+
+      - name: Run woke checker
+        working-directory: docs/
+        run: |
+          make woke
 
   linkcheck:
     name: Link check

.readthedocs.yaml

@@ -13,16 +13,26 @@ build:
   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
     post_create_environment:
       - pip install --upgrade pip
       - pip install checkbox-ng/
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
-   fail_on_warning: true   # Fail on all warnings to avoid broken references
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true # Fail on all warnings to avoid broken references
 
 # Optionally declare the Python requirements required to build your docs
 python:
-   install:
-   - requirements: docs/.sphinx/requirements.txt
+  install:
+    - requirements: docs/.sphinx/requirements.txt

docs/.custom_wordlist.txt

@@ -0,0 +1,12 @@
+debhelper
+ethernet
+gen_control
+json
+Makefile
+mylauncher
+nlink_info_kind
+nlink_type
+noperstate
+plainbox
+subprocess
+unary

docs/.gitignore

@@ -1,8 +1,26 @@
-/*env*/
-.sphinx/venv
+# 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
+        }
+    }
+}