Spell Checking

Good documentation requires accurate spelling. Great-Docs includes a built-in spell checker that scans your documentation source files for spelling errors while intelligently skipping code, URLs, and technical terms.

What Gets Scanned

The spell checker scans source documentation, not generated output:

• Files in user_guide/ directory (.qmd and .md files)
• README.md in the project root
• Optionally: docstrings from your Python source code

It does not scan the great-docs/ build directory, as that contains generated output.

Basic Usage

Run the spell checker from your project directory:

great-docs spell-check

The spell checker will scan all .qmd and .md files in your user_guide/ directory and report any misspellings found.

Verbose Output

For detailed progress information, use the --verbose flag:

great-docs spell-check --verbose

This shows each file as it’s scanned:

✅ user_guide/index.qmd: OK
📄 user_guide/guide.qmd: 2 issue(s)
✅ user_guide/reference.qmd: OK

Custom Dictionary

Adding Words on the Command Line

For project-specific terminology, add custom words using -d:

great-docs spell-check -d "griffe" -d "pkgdown" -d "navbar"

Using a Dictionary File

For larger custom dictionaries, create a text file with one word per line:

custom_words.txt

griffe
pkgdown
docstring
navbar
frontmatter

Then reference it with --dictionary-file:

great-docs spell-check --dictionary-file custom_words.txt

Smart Content Skipping

The spell checker automatically skips content that shouldn’t be spell-checked:

Content Type	Example
Code blocks	```python...```
Inline code	`function_name`
URLs	https://example.com
Email addresses	user@example.com
YAML frontmatter	--- title: "Page" ---
HTML tags	<div class="example">
Quarto directives	{.callout-note}
LaTeX math	$x^2 + y^2$
File paths	/path/to/file.py

Built-in Technical Terms

Common programming and documentation terms are automatically recognized:

• Languages: python, javascript, typescript, rust, etc.
• Tools: pytest, numpy, pandas, sphinx, mkdocs, etc.
• Formats: json, yaml, toml, html, css, etc.
• Abbreviations: api, cli, sdk, url, etc.
• Documentation: docstring, frontmatter, readme, changelog, etc.

Checking Docstrings

To also scan Python docstrings in your package:

great-docs spell-check --include-docstrings

This uses griffe to extract docstrings from your Python modules.

CI/CD Integration

JSON Output

For programmatic processing, use --json-output:

great-docs spell-check --json-output

This returns structured JSON:

{
  "total_words": 1234,
  "misspelled": [
    {
      "word": "documment",
      "suggestions": ["document", "documents"],
      "files": ["user_guide/guide.qmd"],
      "contexts": ["This documment explains..."]
    }
  ],
  "by_file": {
    "user_guide/guide.qmd": ["documment"]
  },
  "skipped_files": []
}

GitHub Actions

Add spell checking to your CI workflow:

.github/workflows/docs.yml

name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  spell-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install great-docs

      - name: Run spell check
        run: great-docs spell-check --dictionary-file custom_words.txt

Pre-commit Hook

Add spell checking as a pre-commit hook:

.pre-commit-config.yaml

repos:
  - repo: local
    hooks:
      - id: spell-check
        name: Spell Check Documentation
        entry: great-docs spell-check
        language: system
        types: [markdown]
        pass_filenames: false

Exit Codes

Code	Meaning
0	No spelling issues found
1	Spelling issues found or error occurred

Best Practices

1. Create a custom dictionary file for your project-specific terms
2. Run spell check in CI to catch issues early
3. Review suggestions - the spell checker provides up to 5 suggestions for each misspelling
4. Use --verbose when debugging to see exactly what’s being checked
5. Combine with link checking for comprehensive documentation QA:

great-docs check-links && great-docs spell-check

Programmatic Usage

You can also use the spell checker programmatically:

from great_docs import GreatDocs

docs = GreatDocs()

# Basic spell check
results = docs.spell_check()
print(f"Checked {results['total_words']} words")
print(f"Found {len(results['misspelled'])} misspellings")

# With custom dictionary
results = docs.spell_check(
    custom_dictionary=["griffe", "pkgdown"],
    verbose=True
)

# Include docstrings
results = docs.spell_check(include_docstrings=True)

# Process results
for item in results['misspelled']:
    print(f"'{item['word']}' in {item['files']}")
    print(f"  Suggestions: {item['suggestions'][:3]}")