All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading