[docs] Updates starter pack & enables GA (#226)

Author: afgambin

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

@@ -1,9 +1,16 @@
-name: Main Documentation Checks
+#
+name: Automatic doc checks
 
 on:
-  - push
-  - pull_request
-  - workflow_dispatch
+  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 }}
@@ -13,4 +20,5 @@ jobs:
   documentation-checks:
     uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
     with:
-      working-directory: 'docs'
+      working-directory: "docs"
+      fetch-depth: 0

docs/.custom_wordlist.txt

@@ -19,6 +19,7 @@ intel
 IPEX
 ipynb
 ITEX
+jovyan
 Jupyter
 jupyter
 JupyterLab

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

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

docs/.gitignore

@@ -12,7 +12,16 @@ build:
     python: "3.11"
   jobs:
     post_checkout:
-      - cd docs && python3 .sphinx/build_requirements.py
+    - 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:
@@ -22,9 +31,9 @@ sphinx:
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 formats:
-   - pdf
+- pdf
 
 # Optionally declare the Python requirements required to build your docs
 python:
-   install:
-   - requirements: docs/.sphinx/requirements.txt
+  install:
+  - requirements: docs/requirements.txt

docs/.readthedocs.yaml

@@ -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/.markdownlint.json

@@ -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)$