Documentation: Implement automatic spelling check

.github/workflows/build-docs.yml

@@ -40,6 +40,6 @@ jobs:
       - name: Upload documentation artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: sphinx-docs
+          name: django-otp-webauthn-docs
           path: docs/_build/html/
           retention-days: 7

.github/workflows/spellcheck.yml

@@ -0,0 +1,55 @@
+name: Check Documentation Spelling
+
+on:
+  workflow_run:
+    workflows: ["Build Documentation"]
+    types:
+      - completed
+  workflow_dispatch:
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  spelling:
+    runs-on: ubuntu-latest
+    # Only run if the build-docs workflow succeeded or on PR/manual trigger
+    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request' }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download documentation artifacts
+        if: github.event_name == 'workflow_run'
+        uses: actions/download-artifact@v4
+        with:
+          name: django-otp-webauthn-docs
+          path: docs/_build/html/
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools
+          python -m pip install pyspelling
+
+      - name: Install Aspell
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y aspell aspell-en
+
+      - name: Build Documentation (if not from workflow_run)
+        if: github.event_name != 'workflow_run'
+        run: |
+          pip install -e '.[docs]'
+          cd docs && make html
+
+      - name: Spell check
+        working-directory: ./docs
+        run: |
+          python -m pyspelling -c spellingcheck.yaml

docs/.gitignore

@@ -1 +1,2 @@
 _build/
+wordlist.dic

docs/Makefile

@@ -7,19 +7,108 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
+SPELLING_CONFIG = spellingcheck.yaml
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo ""
+	@echo "Additional spelling targets:"
+	@echo "  install-spelling-deps  Install pyspelling and aspell dependencies"
+	@echo "  run                    Build docs and run pyspelling"
+	@echo "  spelling               Run pyspelling on existing build"
 
-.PHONY: help Makefile
+.PHONY: help Makefile install-spelling-deps spelling run
+
+# Check if required dependencies are installed, install if missing
+check-spelling-deps:
+	@echo "Checking for required spelling dependencies..."
+	@if ! command -v aspell >/dev/null 2>&1; then \
+		echo "aspell is not installed. Installing dependencies..."; \
+		$(MAKE) install-spelling-deps; \
+	elif ! python3 -c "import pyspelling" 2>/dev/null; then \
+		echo "pyspelling is not installed. Installing dependencies..."; \
+		$(MAKE) install-spelling-deps; \
+	else \
+		echo "All spelling dependencies are installed."; \
+	fi
+
+# Install spelling dependencies
+install-spelling-deps:
+	@echo "Installing spelling dependencies..."
+	@echo "Detecting operating system..."
+	@if command -v apt-get >/dev/null 2>&1; then \
+		echo "Detected Debian/Ubuntu system"; \
+		echo "Installing aspell and aspell-en..."; \
+		sudo apt-get update && sudo apt-get install -y aspell aspell-en; \
+	elif command -v yum >/dev/null 2>&1; then \
+		echo "Detected RHEL/CentOS system"; \
+		echo "Installing aspell and aspell-en..."; \
+		sudo yum install -y aspell aspell-en; \
+	elif command -v dnf >/dev/null 2>&1; then \
+		echo "Detected Fedora system"; \
+		echo "Installing aspell and aspell-en..."; \
+		sudo dnf install -y aspell aspell-en; \
+	elif command -v pacman >/dev/null 2>&1; then \
+		echo "Detected Arch Linux system"; \
+		echo "Installing aspell and aspell-en..."; \
+		sudo pacman -S --noconfirm aspell aspell-en; \
+	elif [ "$$(uname)" = "Darwin" ]; then \
+		echo "Detected macOS system"; \
+		if command -v brew >/dev/null 2>&1; then \
+			echo "Found Homebrew, installing aspell..."; \
+			brew install aspell; \
+		elif command -v port >/dev/null 2>&1; then \
+			echo "Found MacPorts, installing aspell..."; \
+			sudo port install aspell aspell-dict-en; \
+		else \
+			echo "Neither Homebrew nor MacPorts found."; \
+			echo "Please install aspell manually:"; \
+			echo "  - Install Homebrew: https://brew.sh"; \
+			echo "  - Then run: brew install aspell"; \
+			echo "  - Or install MacPorts: https://www.macports.org"; \
+			echo "  - Then run: sudo port install aspell aspell-dict-en"; \
+			exit 1; \
+		fi \
+	else \
+		echo "Could not detect package manager."; \
+		echo "Please manually install aspell and aspell-en for your system."; \
+		echo "Common package names: aspell, aspell-en"; \
+		exit 1; \
+	fi
+	@echo "Installing pyspelling via pip..."
+	@python3 -m pip install pyspelling
+	@echo "Spelling dependencies installed successfully!"
+	@echo "You can now run 'make run' to build docs and check spelling."
+
+# Check dependencies, install if needed, build HTML documentation, run pyspelling, then serve
+run: check-spelling-deps
+	@echo "Building HTML documentation..."
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Running spelling check..."
+	@if [ ! -f "$(SPELLING_CONFIG)" ]; then \
+		echo "Error: Spelling config file '$(SPELLING_CONFIG)' not found."; \
+		exit 1; \
+	fi
+	pyspelling -c $(SPELLING_CONFIG)
+	@echo "Press Ctrl+C to stop the server"
+	sphinx-autobuild -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Run pyspelling on existing build
+spelling: check-spelling-deps
+	@echo "Running pyspelling with config: $(SPELLING_CONFIG)"
+	@if [ ! -f "$(SPELLING_CONFIG)" ]; then \
+		echo "Error: Spelling config file '$(SPELLING_CONFIG)' not found."; \
+		exit 1; \
+	fi
+	@if [ ! -d "$(BUILDDIR)/html" ]; then \
+		echo "Error: HTML build directory '$(BUILDDIR)/html' not found."; \
+		echo "Please run 'make html' first to build the documentation."; \
+		exit 1; \
+	fi
+	pyspelling -c $(SPELLING_CONFIG) -j 8
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-# Start a local development server to automatically rebuild and serve the HTML documentation
-# whenever changes are made to the source files.
-run:
-	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/contributing/index.rst

@@ -10,9 +10,9 @@ Propose changes
 
 The following steps provide an overview of the process involved in proposing changes to Django OTP WebAuthn:
 
-1. Create an issue in the repository to outline the proposed changes.
+1. Create an issue in the `repository <https://github.com/Stormbase/django-otp-webauthn>`_ to outline the proposed changes.
 
-2. Fork the `repository <https://github.com/Stormbase/django-otp-webauthn>`_ and create a new branch for the changes.
+2. Fork the repository and create a new branch for the changes.
 
 3. :ref:`set-up-django-otp-webauthn`.
 
@@ -236,13 +236,7 @@ To build the documentation on your local machine, follow these steps:
 
         cd docs
 
-3. Build the documentation:
-
-    .. code-block:: console
-
-        make html
-
-4. Serve and watch for changes:
+3. Build and serve the documentation, then watch for changes :
 
     .. code-block:: console
 

docs/spellingcheck.yaml

@@ -0,0 +1,29 @@
+matrix:
+  - name: HTML files
+    aspell:
+      lang: en
+      d: en_US
+      encoding: utf-8
+    dictionary:
+      wordlists:
+        - wordlist.txt
+      output: wordlist.dic
+    sources:
+      - _build/html/**/*.html|!_build/html/index.html|!_build/html/contributing/style_guide.html|!_build/html/glossary.html|!_build/html/genindex.html|!_build/html/search.html
+    pipeline:
+      - pyspelling.filters.html:
+          comments: false
+          attributes:
+            - title
+            - alt
+          ignores:
+            - code
+            - pre
+            - spellexception
+            - link
+            - title
+            - div.relatedlinks
+            - strong.command
+            - div.visually-hidden
+            - img
+            - a.p-navigation__link

docs/wordlist.txt

@@ -0,0 +1,56 @@
+AbstractWebAuthnAttestation
+AbstractWebAuthnCredential
+auth
+authenticator
+authenticator's
+authenticators
+authenticatorSelection
+backend
+backends
+backticks
+BeginCredentialAuthenticationView
+BeginCredentialRegistrationView
+biometric
+biometrics
+Caddy
+ccTLD
+CompleteCredentialAuthenticationView
+CompleteCredentialRegistrationView
+cryptographic
+django
+Frontend
+frontend
+Furo
+gettext
+github
+http
+htmlcov
+HTTPS
+js
+JSON
+localhost
+OneToOneField
+OTP
+OTPMiddleware
+otp
+passwordless
+pradyunsg
+pre
+PyPI
+py
+Quickstart
+rpID
+rpIDs
+reStructuredText
+residentKey
+Stormbase
+subclasses
+subclassing
+untrusted
+WebAuthn
+webauthn
+WebAuthn's
+WebAuthnCredential
+WebAuthnUserHandle
+WellKnownWebAuthnView
+YubiKey

pyproject.toml

@@ -66,6 +66,7 @@ docs = [
   "sphinx_design==0.6.1",
   "sphinx-copybutton==0.5.2",
   "sphinx-autobuild==2024.10.3",
+  "pyspelling==2.10",
 ]
 
 [project.urls]
@@ -110,7 +111,7 @@ include = [
 
 [tool.hatch.envs.default]
 dependencies = [
-  "django-otp-webauthn[testing]",
+  "django-otp-webauthn[testing,docs]",
 ]
 
 [tool.hatch.envs.hatch-static-analysis]