Update breaking changes from starter-pack and improve workflow (#220)

- There are recent breaking changes in
canonical/sphinx-docs-starter-pack that causes our workflow to fail.
Align those changes in COU to fix the issue.
- Update the workflow to only trigger documentation checks if a PR
modifies `docs/`. This will prevent un-necessary runs. I'm keeping the
on.push as is because I think it is good to have a way to notify us
about dependency breakage (those issues are not affecting live doc
site).

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

@@ -1,9 +1,12 @@
 name: Main Documentation Checks
 
 on:
-  - push
-  - pull_request
-  - workflow_dispatch
+  push:
+  pull_request:
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

docs/.custom_wordlist.txt

@@ -20,4 +20,5 @@ OpenStackApplication
 yaml
 backoff
 BACKOFF
-websockets
+websockets
+enablement

docs/Makefile

@@ -77,10 +77,10 @@ serve: html
 clean: clean-doc
 	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
 	rm -rf $(VENVDIR)
-	rm -rf .sphinx/.doctrees
 
 clean-doc:
 	git clean -fx "$(BUILDDIR)"
+	rm -rf .sphinx/.doctrees
 
 spelling: html
 	. $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml
@@ -93,7 +93,7 @@ woke: woke-install
 	    -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
 
 pa11y: pa11y-install html
-	find $(BUILDDIR) -name *.html -exec $(PA11Y) {} \;
+	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).