Documentation: Implement automatic spelling check #77
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #77 +/- ##
=======================================
Coverage 100.0% 100.0%
=======================================
Files 13 13
Lines 748 748
Branches 63 63
=======================================
Hits 748 748 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
Hey @activus-d sorry for leaving things open so long 🙏
It looks like this processes the compiled HTML documentation. Did you try to see if it is possible to run it on RST source files? That way the error messages might be more helpful, right now they reference the HTML files instead of the source.
Does the spell check run in GitHub actions (or in the ReadTheDocs build) so we can check we are not introducing new spelling mistakes?
| 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." |
There was a problem hiding this comment.
@activus-d where did you source this list from?
There was a problem hiding this comment.
What list are you referring to here, Storm?
There was a problem hiding this comment.
'list' -> the list of checks for operating system and package installation commands
There was a problem hiding this comment.
Regarding the Pyspelling dependencies, it uses either Aspell or Hunspell. I used Aspell for this project. See the Pyspelling Setup & Overview page for more information.
Regarding the OS commands, I found the information online, but I can’t retrieve the sources because I cleared my browser history. Unfortunately, I’ve only been able to test them on my Mac M2 (Darwin) so far.
Welcome back, Storm. Unfortunately, pyspelling doesn’t support
Yes, we can configure it to run in GitHub actions. |
|
@activus-d alright, we will have to live with those limitations then. Remaining points from me:
|
Of course, my plan has always been to document it after you review the setup and we agree on it. |
I might have to create a separate PR for this, since any GitHub Actions config has to be merged into the default branch before it will work. |
|
@activus-d you can commit to main in your own fork and see the actions run there |
…name in build-docs.yml; update wordlist.txt dictionary
|
@Stormheg I’ve made a new commit to check the spelling of built HTML files in CI. |
This PR solves issue #76 by implementing an automatic spell checking for the documentation using pyspelling instead of sphinxcontrib.spelling.
Changes Introduced
docs/Makefileto include:aspellandpyspellingacross common operating systems.spellingcheck.yaml: Configurespyspellingto check built HTML files, excluding pages like glossary, index, and style guide.docs/wordlist.txt, a custom dictionary of valid project-specific terms.pyproject.tomlto include pyspelling as a documentation dependency..gitignore rulesto exclude docs/wordlist.dic.contributing/index.rst: