{"id":2777,"library":"sphinxcontrib-spelling","title":"Sphinx Spelling Extension","description":"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]","status":"active","version":"8.0.2","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/spelling","tags":["sphinx","documentation","spell-check","extension","pyenchant"],"install":[{"cmd":"pip install sphinxcontrib-spelling","lang":"bash","label":"Install using pip"},{"cmd":"sudo apt-get install enchant\npip install pyenchant sphinxcontrib-spelling","lang":"bash","label":"Install system Enchant and Python packages (Debian/Ubuntu example)"}],"dependencies":[{"reason":"Provides the core spell-checking dictionaries and functionality. While optional for installation, spell checking will not work without it.","package":"PyEnchant","optional":true},{"reason":"This is a Sphinx extension and requires Sphinx to operate.","package":"Sphinx"}],"imports":[{"note":"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.","symbol":"'sphinxcontrib.spelling'","correct":"# in conf.py\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.spelling'\n]"}],"quickstart":{"code":"# 1. Install PyEnchant and sphinxcontrib-spelling (see install instructions).\n# 2. In your Sphinx project's conf.py file:\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.spelling'\n]\n\nspelling_lang = 'en_US'\nspelling_word_list_filename = ['spelling_wordlist.txt']\nspelling_show_suggestions = True\n\n# 3. Create a 'spelling_wordlist.txt' file in your project root with custom words (one per line).\n#    Example: 'MyBrandName', 'JargonTerm'\n\n# 4. Build your documentation to check spelling. Run this command in your project root:\n#    sphinx-build -b spelling docs/source docs/build/spelling\n#    (Assuming 'docs/source' is your source directory and 'docs/build' is your build directory.)","lang":"python","description":"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]"},"warnings":[{"fix":"Ensure `enchant` (system library) and `pyenchant` (Python package) are correctly installed and discoverable by your Python environment.","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Execute `sphinx-build -b spelling <source_dir> <build_dir>` as a distinct command to perform spell checking.","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to a later stable version (e.g., 8.0.2) or downgrade to a prior stable version if necessary.","message":"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]","severity":"breaking","affected_versions":"7.7.1"},{"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.","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `sphinxcontrib-spelling` version 8.0.0 or newer to ensure compatibility with Sphinx 8.2+.","message":"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]","severity":"breaking","affected_versions":"<8.0.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}