docs: Update to the latest version of the Sphinx Stack

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

@@ -1,11 +1,13 @@
-name: Main Documentation Checks
+#
+name: Automatic doc checks
 
 on:
   push:
-    branches: [main]
+    branches: [ main ]
   pull_request:
     paths:
-      - "docs/**" # Only run on changes to the docs directory
+      - 'docs/**'   # Only run on changes to the docs directory
+
   workflow_dispatch:
     # Manual trigger
 

.github/workflows/check-removed-urls.yml

@@ -0,0 +1,56 @@
+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} \
+            | grep -v '^\./explanation/security/full-disk-encryption/$' || true)
+          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

@@ -21,4 +21,4 @@ jobs:
         fetch-depth: 0
     - uses: DavidAnson/markdownlint-cli2-action@b4c9feab76d8025d1e83c653fa3990936df0e6c8 # Commit hash for v16 tag
       with:
-        config: "docs/.sphinx/.markdownlint.json"
+        config: "docs/_dev/.markdownlint.json"

docs/.custom_wordlist.txt

@@ -147,6 +147,7 @@ Permalink
 PKI
 POSIX
 pre
+preboot
 prometheus
 radosgw
 ReadMe
@@ -192,6 +193,7 @@ API
 APIs
 arounds
 Auth
+AZs
 auth
 authorization
 auto-generated
@@ -204,6 +206,7 @@ catalog
 centralized
 Centralized
 ceph
+cephadm
 CephFS
 CephHealthWarning
 Cephx
@@ -280,9 +283,12 @@ manpage
 md
 mds
 MDS
+MDSs
 mees
 mentorship
 MgrReports
+MGRs
+MONs
 MiB
 MicroCeph
 MicroCeph's
@@ -320,6 +326,7 @@ qemu
 radosgw
 rbd
 RBD
+reachability
 readme
 ReadMe
 reST
@@ -328,6 +335,7 @@ reStructuredText
 resync
 rgw
 RGW
+RGWs
 RO
 rsyslog
 RTD
@@ -389,10 +397,13 @@ Hyperconverged
 RadosGW
 NICs
 OOB
+SSDs
 SSD
 SSHing
 unpartitioned
 GateWay
+Gbps
+HDDs
 Certbot
 LetsEncrypt
 utilize

docs/.gitignore

@@ -1,17 +1,17 @@
 # Environment
 *env*/
-.sphinx/venv/
+.venv/
 
 # Sphinx
-.sphinx/warnings.txt
-.sphinx/.wordlist.dic
-.sphinx/.doctrees/
-.sphinx/update/
-.sphinx/node_modules/
+_dev/warnings.txt
+_dev/.wordlist.dic
+_dev/.doctrees/
+_dev/update/
+_dev/node_modules/
 
 # Vale
-.sphinx/styles/*
-.sphinx/vale.ini
+_dev/styles/*
+_dev/vale.ini
 
 # Build outputs
 _build