Update to the latest sphinx stack

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

@@ -0,0 +1,23 @@
+#
+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,55 @@
+name: Check for removed URLs
+
+on:
+  workflow_call:
+  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 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,17 @@
+# 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]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+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,28 @@
+name: Markdown style checks
+
+on:
+  workflow_call:
+  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-24.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

.github/workflows/sphinx-python-dependency-build-checks.yml

@@ -9,48 +9,44 @@
 # Depending on the architecture, pip may or may not have already built wheels
 # available, and as such we need to make sure building wheels from source can
 # succeed.
-name: Check and document build requirements for Sphinx venv
+name: Sphinx python dependency build checks
+
 on:
   push:
-    paths:
-      - 'conf.py'
-      - 'custom_conf.py'
+    branches: [ main ]
   pull_request:
-    paths:
-      - 'conf.py'
-      - 'custom_conf.py'
-  workflow_dispatch:
-
+  workflow_call:
+  workflow_dispatch: # manual trigger
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true  
+  cancel-in-progress: true
 
 jobs:
   build:
     name: build
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install dependencies
-        run: |
-          set -ex
-          sudo apt -y install \
-            cargo \
-            libpython3-dev \
-            libxml2-dev \
-            libxslt1-dev \
-            make \
-            python3-venv \
-            rustc \
-            libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk libharfbuzz-dev libfribidi-dev libxcb1-dev
+    - name: Checkout code
+      uses: actions/checkout@v5
 
-      - name: Build Sphinx venv
-        run: |
-          set -ex
-          make -f Makefile.sp \
-            sp-install \
-            PIPOPTS="--no-binary :all:" \
-            || ( cat .sphinx/venv/pip_install.log && exit 1 )
+    - name: Install dependencies
+      run: |
+        set -ex
+        sudo apt-get --fix-missing update
+        sudo apt-get -y install \
+          cargo \
+          libpython3-dev \
+          libxml2-dev \
+          libxslt1-dev \
+          make \
+          python3-venv \
+          rustc \
+          libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk libharfbuzz-dev libfribidi-dev libxcb1-dev
+    - name: Build Sphinx venv
+      working-directory: "docs"
+      run: |
+        set -ex
+        make install \
+          PIPOPTS="--no-binary :all:" \
+          || ( cat .venv/pip_install.log && exit 1 )

.gitignore

@@ -1,15 +1,9 @@
 /*env*/
-.sphinx/venv/
-.sphinx/requirements.txt
-.sphinx/warnings.txt
-.sphinx/.wordlist.dic
-.sphinx/.doctrees/
-.sphinx/node_modules/
+**/.venv/
+**/.doctrees/
 package*.json
-_build
+docs/_build
 .DS_Store
 __pycache__
 .idea/
 .vscode/
-.sphinx/styles/*
-.sphinx/vale.ini

.readthedocs.yaml

@@ -11,21 +11,29 @@ build:
   tools:
     python: "3.11"
   jobs:
-    pre_install:
-      - python3 .sphinx/build_requirements.py
-      - git fetch --unshallow || true
+    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: conf.py
+  configuration: docs/conf.py
   fail_on_warning: true
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
-#formats:
-#   - pdf
+formats:
+- pdf
 
 # Optionally declare the Python requirements required to build your docs
 python:
-   install:
-   - requirements: .sphinx/requirements.txt
+  install:
+  - requirements: docs/requirements.txt