Sphinx Spelling Extension

8.0.2 · active · verified Fri Apr 10

sphinxcontrib.spelling is a spelling checker extension for Sphinx-based documentation. It leverages PyEnchant to analyze reStructuredText and Markdown files, generating reports of misspelled words. The current version is 8.0.2, and the project maintains an active development with regular releases addressing bugs and adding features. [1, 3, 11, 12, 14]

Warnings

gotcha The spell checking functionality relies on PyEnchant, which requires a system-level Enchant library to be installed. If PyEnchant is not installed or correctly configured with Enchant, spell checking will not work, though the extension itself might initialize without error. [1, 13, 20]
Fix: Ensure `enchant` (system library) and `pyenchant` (Python package) are correctly installed and discoverable by your Python environment.
gotcha The spell checker runs as a dedicated Sphinx builder. It does not automatically run when you build other formats like HTML or LaTeX. You must explicitly run `sphinx-build -b spelling` as a separate step. [5, 8]
Fix: Execute `sphinx-build -b spelling <source_dir> <build_dir>` as a distinct command to perform spell checking.
breaking Version `7.7.1` was yanked from PyPI because it introduced a breaking change without a corresponding semantic version update. Users should avoid this specific version. [12]
Fix: Upgrade to a later stable version (e.g., 8.0.2) or downgrade to a prior stable version if necessary.
gotcha Spell check results can be inconsistent across different operating systems or environments (e.g., Windows vs. Linux CI/CD). This is often due to variations in PyEnchant's underlying Enchant dictionary installations or configurations. [20]
Fix: Standardize the Enchant and PyEnchant installations across all development and build environments, potentially specifying exact versions or using Docker for consistency. Configure `spelling_lang` explicitly.
breaking Older versions (prior to 8.0.0) might encounter a `TypeError` when processing nodes without source information, especially with Sphinx 8.2 or newer. [19]
Fix: Upgrade to `sphinxcontrib-spelling` version 8.0.0 or newer to ensure compatibility with Sphinx 8.2+.

Install

pip install sphinxcontrib-spelling Install using pip
sudo apt-get install enchant pip install pyenchant sphinxcontrib-spelling Install system Enchant and Python packages (Debian/Ubuntu example)

Imports

'sphinxcontrib.spelling'
```
# in conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.spelling'
]
```
The extension is enabled by adding its module name to the 'extensions' list in Sphinx's conf.py. There are no direct Python imports of classes from sphinxcontrib.spelling for typical usage.

Quickstart

To quickly set up `sphinxcontrib-spelling`, first ensure PyEnchant and the extension are installed. Then, configure your Sphinx `conf.py` to include the extension and define basic spelling options like language and custom word lists. Finally, run the `sphinx-build` command with the `-b spelling` option to execute the spell checker, which will output misspelled words to the console and a log file. [4, 8, 9, 15]

# 1. Install PyEnchant and sphinxcontrib-spelling (see install instructions).
# 2. In your Sphinx project's conf.py file:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.spelling'
]

spelling_lang = 'en_US'
spelling_word_list_filename = ['spelling_wordlist.txt']
spelling_show_suggestions = True

# 3. Create a 'spelling_wordlist.txt' file in your project root with custom words (one per line).
#    Example: 'MyBrandName', 'JargonTerm'

# 4. Build your documentation to check spelling. Run this command in your project root:
#    sphinx-build -b spelling docs/source docs/build/spelling
#    (Assuming 'docs/source' is your source directory and 'docs/build' is your build directory.)

view raw JSON →