From 642fb6af42033273cd70b8d92c8987ab05194417 Mon Sep 17 00:00:00 2001 From: activus-d Date: Fri, 11 Jul 2025 12:39:56 +0100 Subject: [PATCH 1/4] Implement automatic spelling check on HTML build using pyspelling --- docs/.gitignore | 1 + docs/Makefile | 101 +++++++++++++++++++++++++++++++++--- docs/contributing/index.rst | 12 ++--- docs/spellingcheck.yaml | 29 +++++++++++ docs/wordlist.txt | 50 ++++++++++++++++++ pyproject.toml | 3 +- 6 files changed, 180 insertions(+), 16 deletions(-) create mode 100644 docs/spellingcheck.yaml create mode 100644 docs/wordlist.txt diff --git a/docs/.gitignore b/docs/.gitignore index 69fa449..b84c0b3 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ _build/ +wordlist.dic diff --git a/docs/Makefile b/docs/Makefile index e3d96dd..123f209 100644 --- a/docs/Makefile +++ b/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) diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 6068111..d6a1891 100644 --- a/docs/contributing/index.rst +++ b/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 `_ to outline the proposed changes. -2. Fork the `repository `_ 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 diff --git a/docs/spellingcheck.yaml b/docs/spellingcheck.yaml new file mode 100644 index 0000000..901ed2f --- /dev/null +++ b/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 diff --git a/docs/wordlist.txt b/docs/wordlist.txt new file mode 100644 index 0000000..85b6a65 --- /dev/null +++ b/docs/wordlist.txt @@ -0,0 +1,50 @@ +AbstractWebAuthnAttestation +AbstractWebAuthnCredential +auth +authenticator +authenticator's +authenticators +authenticatorSelection +backends +backticks +BeginCredentialAuthenticationView +BeginCredentialRegistrationView +biometric +biometrics +Caddy +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 +reStructuredText +residentKey +Stormbase +subclasses +subclassing +untrusted +WebAuthn +webauthn +WebAuthnCredential +WebAuthnUserHandle +YubiKey diff --git a/pyproject.toml b/pyproject.toml index ab0c7d3..f02cbdc 100644 --- a/pyproject.toml +++ b/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] From eb430f10abcf97dee5e4a5dd3fb38c3faeb8b603 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 15 Jul 2025 03:50:10 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/spellingcheck.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spellingcheck.yaml b/docs/spellingcheck.yaml index 901ed2f..6bf5b8e 100644 --- a/docs/spellingcheck.yaml +++ b/docs/spellingcheck.yaml @@ -9,7 +9,7 @@ matrix: - 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 + - _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 From c3e4008d9ac9aff5a57f8ad6d7606b3f4b0c0891 Mon Sep 17 00:00:00 2001 From: activus-d Date: Mon, 25 Aug 2025 12:27:15 +0100 Subject: [PATCH 3/4] add config file for spelling check workflow in CI; update built docs name in build-docs.yml; update wordlist.txt dictionary --- .github/workflows/build-docs.yml | 2 +- .github/workflows/spellcheck.yml | 55 ++++++++++++++++++++++++++++++++ docs/wordlist.txt | 6 ++++ 3 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/spellcheck.yml diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 4a04391..cdf58d8 100644 --- a/.github/workflows/build-docs.yml +++ b/.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 diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml new file mode 100644 index 0000000..84b7bf0 --- /dev/null +++ b/.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 diff --git a/docs/wordlist.txt b/docs/wordlist.txt index 85b6a65..beac3c0 100644 --- a/docs/wordlist.txt +++ b/docs/wordlist.txt @@ -5,6 +5,7 @@ authenticator authenticator's authenticators authenticatorSelection +backend backends backticks BeginCredentialAuthenticationView @@ -12,6 +13,7 @@ BeginCredentialRegistrationView biometric biometrics Caddy +ccTLD CompleteCredentialAuthenticationView CompleteCredentialRegistrationView cryptographic @@ -37,6 +39,8 @@ pre PyPI py Quickstart +rpID +rpIDs reStructuredText residentKey Stormbase @@ -45,6 +49,8 @@ subclassing untrusted WebAuthn webauthn +WebAuthn's WebAuthnCredential WebAuthnUserHandle +WellKnownWebAuthnView YubiKey From 6b16a90ab5f97231c5a451b1d71520f2ca2132a1 Mon Sep 17 00:00:00 2001 From: activus-d Date: Mon, 25 Aug 2025 12:48:01 +0100 Subject: [PATCH 4/4] trim trailing whitespace --- .github/workflows/spellcheck.yml | 76 ++++++++++++++++---------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 84b7bf0..5825743 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -14,42 +14,42 @@ jobs: 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 + - 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