# Add a Typo Check to a Sphinx Documentation Site

Yes. An agent adds the typos checker as a pre-commit hook, so your existing lint job runs it, fixes what it finds in the docs and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-typo-check/sphinx/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with how the documentation is built and linted. In a project laid out like psf/black, the docs live in `docs/` as 28 Markdown files read by `myst_parser`, with `docs/conf.py` listing `sphinx.ext.autodoc`, `sphinx.ext.intersphinx`, `sphinx.ext.napoleon`, `sphinxcontrib.programoutput` and `sphinx_copybutton`, and `source_suffix` accepting both `.rst` and `.md`. The `docs` dependency group in `pyproject.toml` pins `sphinx==9.1.0`, `myst-parser==5.1.0`, `furo` and `docutils`, and `.github/workflows/docs.yml` installs it and runs `sphinx-build -a -b html -W --keep-going docs/ docs/_build` on Ubuntu and Windows. `docs/change_log.md` is a single `{include}` of the 2,717-line `CHANGES.md` at the repository root, with a hook in `conf.py` that turns `#1234` references into pull request links, so the changelog is part of the site too.

Linting runs through pre-commit: `.github/workflows/lint.yml` installs the `tox` group and calls `pre-commit/action`, and `.pre-commit-config.yaml` lists isort, flake8 with three plugins, mypy, prettier for Markdown, YAML and JSON, and the end-of-file and trailing-whitespace fixers, with `profiling/` and `tests/data/` excluded. Nothing checks spelling; the only trace is a 2021 changelog entry about typos found by codespell once. Because CI already runs every hook in that file, the agent adds the `typos` hook from `crate-ci/typos`, pinned to a release tag, to `.pre-commit-config.yaml` rather than writing a new workflow. The job in `lint.yml` picks it up with no change, contributors get the same check locally from `pre-commit run -a`, and the daily Dependabot run that already covers `github-actions` and `pip` is joined by pre-commit's own autoupdate for the hook revision.

The configuration is `_typos.toml` at the root. Its `[files]` table excludes `tests/data/`, which holds formatter fixtures including one named `incorrect_spelling.toml` whose misspellings are the test, `src/blib2to3/`, the vendored parser that flake8 already skips, and `profiling/`. Its `[default.extend-words]` and `[default.extend-identifiers]` tables take the terms the first run flags, each with a comment saying where the word is used and why it stays: option names, the names of tools in `docs/compatible_configs/`, and identifiers quoted inside fenced code in `docs/the_black_code_style/`. The agent installs the checker with `pip install typos` and runs `typos` from the root, then works through the report in two piles: prose corrections in `docs/` and `CHANGES.md`, and words that belong in the allow list.

Each prose correction is made in place, and corrections inside `CHANGES.md` are kept to spelling so that no `(#1234)` reference, which the `changelog` workflow greps for, is disturbed. The agent then runs `pre-commit run -a` so prettier reformats any paragraph it touched, and `sphinx-build -W --keep-going` with the pinned docs group so a corrected word inside a MyST directive or a cross-reference target still builds without a warning. The pull request lists every correction as a before-and-after pair grouped by file, and every allow-list entry with its reason.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a typo check to this project's Sphinx documentation. Read docs/conf.py, pyproject.toml, .pre-commit-config.yaml, .github/workflows/lint.yml, .github/workflows/docs.yml and .github/workflows/changelog.yml first. Install typos with pip, write _typos.toml at the root with files.extend-exclude for tests/data/, src/blib2to3/ and profiling/, and run typos from the root. Fix real misspellings in docs/ and CHANGES.md without changing any (#number) reference; put deliberate spellings under default.extend-words and code names under default.extend-identifiers, each with a comment naming where it is used. Add the typos hook from crate-ci/typos, pinned to a release tag, to .pre-commit-config.yaml so the existing lint workflow runs it. Run pre-commit run -a, typos, and sphinx-build -W --keep-going over docs/ until all three exit clean, then open a pull request that lists every correction as a before-and-after pair grouped by file and every allow-list entry with its reason.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `_typos.toml`, adds the `typos` hook to `.pre-commit-config.yaml`, and changes the Markdown under `docs/` and lines of `CHANGES.md` where a word was corrected. Its description lists the corrections as before-and-after pairs grouped by file, the allow-list entries with their reasons, the `pre-commit run -a` result, the `sphinx-build` summary with warnings treated as errors, and the final `typos` exit.

Because `.github/workflows/changelog.yml` fails a pull request whose number is not referenced in `CHANGES.md`, the agent adds its own entry under the unreleased heading in the documentation section, or notes in the description that a maintainer can apply the `ci: skip news` label instead. The `docs` workflow runs on the pull request because it touches `docs/`, so the site build on both operating systems is checked before anyone merges.

Before merging, a reviewer reads the pairs for any spelling that was intentional in context, such as a quoted error message from another tool, and decides whether `CHANGES.md` should be excluded after all, since old entries quote pull request titles verbatim and a correction there changes a historical record more than a reader's experience.

## Run it on every pull request

A team that maintains several Sphinx sites sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own setup: a repository whose lint workflow does not use pre-commit gets a small `typos` job of its own instead of a hook, and one with reStructuredText sources gets the same check, since `typos` reads any text file.

Once the hook exists, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if the lint job failed on the typos hook, read its output and comment with the corrections it suggests, file by file, without pushing" starts one run per pull request. The trigger adds the pull request after the prompt, only work by an owner, member or collaborator fires it, and its runs read the repository and comment rather than push.

## Why run it on Rush?

The first run of a spell checker over a documentation site with thousands of words, a vendored parser, deliberately misspelled fixtures and a changelog that quotes other people is mostly judgement: which hits are errors, which are names, and which files should never be read. The agent makes each call in the open, with a comment in `_typos.toml` and a line in the pull request, and reruns the Sphinx build with warnings as errors so a fix inside a directive never breaks the site.

The checker's output, the pre-commit run and the Sphinx build log stay with the run, so a reviewer sees why each allow-list entry exists. A team with many documentation sites runs the same request across all of them at once, each in its own sandbox, and gets one pull request per repository with its own corrections.

## Frequently asked questions

### Why a pre-commit hook rather than a new workflow?

The lint workflow already runs every hook in `.pre-commit-config.yaml` through `pre-commit/action`, so adding the hook there gives CI the check with no new YAML, and contributors run the same check locally with `pre-commit run -a`. A repository that does not use pre-commit in CI gets a small `typos` job instead.

### Why exclude the test fixtures?

The formatter's fixtures under `tests/data/` include files whose misspellings are the point of the test, such as `incorrect_spelling.toml`, and the vendored parser under `src/blib2to3/` is upstream code that flake8 already skips. Checking them would produce findings nobody should fix.

### Will corrections in CHANGES.md break the changelog check?

The `changelog` workflow greps `CHANGES.md` for the pull request's own number, so the agent adds an entry for its change and keeps every existing `(#number)` reference untouched. The description also offers the `ci: skip news` label as the alternative a maintainer can choose.

### Can a corrected word break the Sphinx build?

It can if the word is a cross-reference target or an option name inside a MyST directive, which is why the agent reruns `sphinx-build -W --keep-going` with the pinned docs group after editing. A word that turns out to be a target goes under `extend-identifiers` instead of being changed.

## More Sphinx jobs

- [Fix "The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0"](https://getrush.ai/run/fix-sphinxcontrib-applehelp-version-error/sphinx/)
- [Add a Copy Button to Sphinx Code Blocks](https://getrush.ai/run/add-copy-button/sphinx/)
- [Add Dark Mode to Sphinx Docs on the Read the Docs Theme](https://getrush.ai/run/add-dark-mode/sphinx/)

## The same job on other stacks

- [Add a Typo Check to Starlight Docs](https://getrush.ai/run/add-typo-check/starlight/)
- [Add a Typo Check to a VitePress Site in CI](https://getrush.ai/run/add-typo-check/vitepress/)
- [Add a Typo Check to a Zola Site](https://getrush.ai/run/add-typo-check/zola/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
