Add codespell: config + action (to detect new typos) and make it fix a good number of them by yarikoptic · Pull Request #11195 · readthedocs/readthedocs.org

yarikoptic · 2024-03-07T23:19:41Z

original

codespell was used occasionally on some files, so not a new tool here. But now it would guard RTD from having typos introduced to begin with.

Note that some fixes could affect (fix) functionality.

There is an odd "variable" syntaxt which I didn't fix since seems would require transition and smells like it is on purpose:

❯ git grep syntaxt -- readthedocs/
readthedocs/projects/migrations/0106_add_addons_config.py:                ("syntaxt", models.CharField(max_length=128)),
readthedocs/projects/models.py:    syntaxt = models.CharField(max_length=128)
readthedocs/projects/tasks/builds.py:        grab them by using glob syntaxt between other files that could be garbage.

or was it intended to be syntax ?

📚 Documentation previews 📚

User's documentation (docs): https://docs--11195.org.readthedocs.build/en/11195/

Developer's documentation (dev): https://dev--11195.org.readthedocs.build/en/11195/

Add codespell configuration and fix existing typos.

More about codespell: https://github.com/codespell-project/codespell

I personally introduced it to over a hundred of projects already mostly with a positive feedback
(see the "improveit-dashboard").

Rebased and reworked from #11195, addressing all review feedback:

Config in .codespellrc (not setup.cfg) — in common/ submodule, symlinked from root
Pre-commit integration instead of standalone GitHub Actions workflow
syntaxt left as-is — Django model field, changing requires DB migration
indx in search test left as-is — intentional non-matching search query, added to ignore-words-list

Depends on the common submodule update (branch enh-codespell on yarikoptic/common fork).
See also readthedocs/common#212.

Changes

Configuration & Infrastructure (`20efc84`)

.codespellrc in common/, symlinked as .codespellrc in root
Codespell added to common/pre-commit-config.yaml as pre-commit hook
Comprehensive skip patterns: locale, migrations, CHANGELOG, media/javascript, search test data, SVG/CSS/AI/minified files
Regex ignores: camelCase/PascalCase identifiers, URLs, hyphenated compounds (re-used, re-declare, pre-selected), long lines, test fixture patterns (pyton, Hel, Ore, Wile E. Coyote)
Word ignores: fo/te (ISO 639 language codes), astroid (library), DED (Django Elasticsearch DSL), syntaxt (DB migration), requestor, indx, ore

Ambiguous Typo Fixes (`f217b0b`)

Manually reviewed and fixed 21 typos where codespell offered multiple suggestions:

neeed → needed/need, explotation → exploitation, interating → iterating
behing → being, achived → achieved, clonned → cloned (×3)
tupe → tuple, toke → token, Thi → This, fom → from
parm → param, containe → container, Custome → Custom
trailling → trailing (and Stripe → Strip in same docstring)
Bulds → Builds, verion → version, treshold → threshold, tha → that

Non-ambiguous Typo Fixes (`4c99a8e`)

50 automatic fixes via codespell -w across 38 files, including:

acccess → access, sligtly → slightly, becuase → because
innecessary → unnecessary, pacakge → package (template variable bug fix!)
intergrations → integrations, susbcription → subscription
runnig → running, overwritting → overwriting, settigs → settings

Potential Bug Fix

{{pacakge}} → {{package}} in config/notifications.py:161 — the template variable name was misspelled, likely causing it to not render. Line 149 already uses the correct {{package}} spelling.

Historical Context

This project has had ~289 prior commits mentioning typos/spelling, demonstrating the value of automated spell-checking.

Testing

✅ Codespell passes with zero errors after all fixes

🤖 Generated with Claude Code

TODOs

needs Add codespell config and pre-commit hook common#294

sentry · 2024-03-07T23:19:52Z

🔍 Existing Issues For Review

Your pull request is modifying functions with the following pre-existing issues:

📄 File: readthedocs/api/v2/views/integrations.py

Function	Unhandled Issue
`get_closed_external_version_response`	TypeError: 'NoneType' object is not subscriptable /api/v2/webhook/{project_slug}/{integration_pk}... `Event Count:` 1

_{Did you find this useful? React with a 👍 or 👎}

humitos

Thanks for the PR 👍🏼

I didn't take a full review, but I noted a few issues that I see will generate some conflicts. In particular, those that change Python code and require some manual interaction (e.g. a Django migration to update the help_text)

I'm not opposed to this work, but I find it hard to prioritize by the core team at this point.

agjohnson · 2024-03-08T18:56:06Z

We use pre-commit for all other linting checks. I feel if we implement this it should be at pre-commit, not GHA.

yarikoptic · 2024-03-08T21:57:57Z

Hmm, interesting, my script should've detected presence of pre-commit config... Will have a look wherever get a chance. You do have ci job running the pre-commit I assume? (I don't see report from pre-commit service)

yarikoptic · 2024-03-08T22:11:04Z

that explains it:

❯ ls -ld .pre-commit-config.yaml
lrwxrwxrwx 1 yoh yoh 29 Mar  7 18:00 .pre-commit-config.yaml -> common/pre-commit-config.yaml
❯ cat .pre-commit-config.yaml
cat: .pre-commit-config.yaml: No such file or directory
❯ git submodule
-4af0fffd2cbeeb40f0a71b875beb99d6dc88a355 common

Let's do the submodules dance now...

Ref: readthedocs/readthedocs.org#11195

humitos · 2025-07-24T12:44:50Z

This PR is great! Thanks for opening it!

I'd like to move forward with it. I've already reviewed readthedocs/common#212

We need to make some adjustments here and we can move forward 👍🏼 . @yarikoptic are you able to continue with this work?

Final decision on fixing or not CHANGELOG.rst

Let's exclude the changelog for now. It has a lot of noise.

let me exclude all such lines with help_text *=.*

We should implement this, if it's not already.

yarikoptic · 2025-07-24T14:47:44Z

We need to make some adjustments here and we can move forward 👍🏼 . @yarikoptic are you able to continue with this work?

I am able as soon as there is cycles on your end so PR doesn't amass conflicts to address again.

Per readthedocs#11195 (comment)

read-the-docs-community · 2025-07-24T15:13:30Z

Documentation build overview

📚 dev | 🛠️ Build #32080278 | 📁 Comparing 4c99a8e against latest (7c6865c)

🔍 Preview build

No files changed.

read-the-docs-community · 2025-07-24T15:13:43Z

Documentation build overview

📚 docs | 🛠️ Build #32080280 | 📁 Comparing 4c99a8e against latest (7c6865c)

🔍 Preview build

Show files changed (1 files in total): 📝 1 modified | ➕ 0 added | ➖ 0 deleted

File	Status
custom-script.html	📝 modified

yarikoptic · 2025-07-24T15:14:23Z

FWIW, I have rebased and redone codespell fixing (automated and interactive). Let's see if no side effects. Please review the diff.

humitos

This is great! I suppose there may be a few test failing because there are some words that shouldn't return search results.

humitos · 2025-07-24T15:21:52Z

            "project": project.slug,
            "version": version.slug,
-            "q": "indx",
+            "q": "index",


This was probably an invalid word on purpose.

so we need to annotate this line to be skipped and ok to contain indx?

I replaced it with explicit "abracadabra" , or it does have to be "indx"? (let's see if tests feel better)

The test is failing. I think it needs to be indx probably for fuzzy search testing. I would leave as it was to avoid this type of issues and probably mark that line to be skipped 👍🏼

Ref: readthedocs/readthedocs.org#11195

humitos · 2025-07-25T12:01:16Z

There is an odd "variable" syntaxt which I didn't fix since seems would require transition and smells like it is on purpose:

This is indeed a typo that I made when I created the model's field AddonSearchFilter.syntaxt, yes 😓 . Let's leave as-is for now because it will require a migration. We can do this in a different PR. It should be easy since this field it's not being used yet.

humitos · 2025-07-25T12:05:14Z

+[codespell]
+# Ref: https://github.com/codespell-project/codespell#using-a-config-file
+skip = .git,*.svg,locale,package-lock.json,*.css,*.min.*,vendor,*.ai,setup.cfg,migrations,CHANGELOG.rst,common
+check-hidden = true
+# some names and abbreviations and very long lines (minimized?)
+# TODO: fixup help_text in readthedocs/builds/models.py : "to perfom an"
+ignore-regex = \b(Manuel|DED|Wile E. Coyote|Couldn\\u2019t|to perfom an)\b|.{300,}|"pyton\b|\|(ative|ment)\||"Hel" will match\b|ative: ''|help_text *=.*
+# TODO: fix syntaxt -- would require transition?
+ignore-words-list = fo,te,astroid,requestor,syntaxt,ore


Is it possible to put all this configuration on a specific codespell file? Like .codespell.cfg or similar?

We will need to put this file into common/ repository (readthedocs/common#212) because we want to share this configuration across multiple repositories, eg. https://github.com/readthedocs/ext-theme

It seems .codespellrc https://github.com/codespell-project/codespell#using-a-config-file

We want that file to be in common/ and symlinked from here 👍🏼

- .codespellrc symlinked from common/.codespellrc - codespell added to common/pre-commit-config.yaml - Updated common submodule to include codespell config - Skips: locale, migrations, CHANGELOG, media/javascript, search test data, SVG/CSS/AI/minified files - Regex ignores: camelCase/PascalCase, URLs, hyphenated compounds, long lines, test fixture patterns - Word ignores: fo/te (ISO 639), astroid, DED, syntaxt (DB migration), requestor, indx, ore Co-Authored-By: Claude Code 2.1.81 / Claude Opus 4.6 <noreply@anthropic.com>

Fixed typos where codespell offered multiple suggestions: - neeed → needed/need (model_views.py, tasks/search.py) - tha → that (permissions.py) - explotation → exploitation (middleware.py) - interating → iterating (utils/__init__.py) - behing → being (sphinx.py) - achived → achieved (sphinx.py) - clonned → cloned (sphinx.py, models.py) - tupe → tuple (version_handling.py) - toke → token (test_oauth.py) - Thi → This, fom → from (git.py) - parm → param (rclone.py) - containe → container (test_api.py) - Custome → Custom (settings/base.py) - trailling → trailing, Stripe → Strip (querysets.py) - Bulds → Builds, verion → version (tasks.py) - treshold → threshold (views/base.py) Co-Authored-By: Claude Code 2.1.81 / Claude Opus 4.6 <noreply@anthropic.com>

… typos === Do not change lines below === { "chain": [], "cmd": "codespell -w", "exit": 0, "extra_inputs": [], "inputs": [], "outputs": [], "pwd": "." } ^^^ Do not change lines above ^^^ Co-Authored-By: Claude Code 2.1.81 / Claude Opus 4.6 <noreply@anthropic.com>

yarikoptic · 2026-04-01T18:02:48Z

@@ -0,0 +1 @@
+common/.codespellrc


FWIW: frankly, I personally would have delayed moving it to common until making sure all is good here

yarikoptic requested review from a team as code owners March 7, 2024 23:19

yarikoptic requested review from agjohnson and ericholscher March 7, 2024 23:19

auto-assign Bot assigned yarikoptic Mar 7, 2024

humitos reviewed Mar 8, 2024

View reviewed changes

Comment thread readthedocs/builds/migrations/0007_add-automation-rules.py Outdated

Comment thread CHANGELOG.rst Outdated

Comment thread .github/workflows/codespell.yml Outdated

Comment thread .github/workflows/codespell.yml Outdated

yarikoptic added a commit to yarikoptic/common that referenced this pull request Mar 8, 2024

Add codespell to pre-commit

ab757de

Ref: readthedocs/readthedocs.org#11195

yarikoptic mentioned this pull request Mar 8, 2024

Pre-commit configuration for codespell readthedocs/common#212

Closed

yarikoptic force-pushed the enh-codespell branch from 51b4bb1 to ef04ef4 Compare March 8, 2024 23:04

yarikoptic marked this pull request as draft March 8, 2024 23:05

yarikoptic force-pushed the enh-codespell branch from ef04ef4 to 120e693 Compare March 8, 2024 23:16

humitos mentioned this pull request Mar 9, 2024

Blog post: How do use vale with RTD readthedocs/website#274

Open

cclauss mentioned this pull request Oct 12, 2024

codespell the docs directory #11664

Merged

yarikoptic force-pushed the enh-codespell branch from 120e693 to 40091fd Compare July 24, 2025 15:12

yarikoptic added a commit to yarikoptic/readthedocs.org that referenced this pull request Jul 24, 2025

Exclude CHANGELOG.rst and help_text files

a7fa169

Per readthedocs#11195 (comment)

humitos reviewed Jul 24, 2025

View reviewed changes

yarikoptic force-pushed the enh-codespell branch from 40091fd to c5202bd Compare July 24, 2025 15:56

yarikoptic added a commit to yarikoptic/common that referenced this pull request Jul 24, 2025

Add codespell to pre-commit

89e3662

Ref: readthedocs/readthedocs.org#11195

humitos reviewed Jul 25, 2025

View reviewed changes

yarikoptic and others added 3 commits April 1, 2026 00:11

yarikoptic force-pushed the enh-codespell branch from c5202bd to 4c99a8e Compare April 1, 2026 17:54

yarikoptic mentioned this pull request Apr 1, 2026

Add codespell config and pre-commit hook readthedocs/common#294

Open

yarikoptic commented Apr 1, 2026

View reviewed changes

Uh oh!

Conversation

yarikoptic commented Mar 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Configuration & Infrastructure (20efc84)

Ambiguous Typo Fixes (f217b0b)

Non-ambiguous Typo Fixes (4c99a8e)

Potential Bug Fix

Historical Context

Testing

Uh oh!

sentry Bot commented Mar 7, 2024

🔍 Existing Issues For Review

Uh oh!

humitos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

agjohnson commented Mar 8, 2024

Uh oh!

yarikoptic commented Mar 8, 2024

Uh oh!

yarikoptic commented Mar 8, 2024

Uh oh!

humitos commented Jul 24, 2025

Uh oh!

yarikoptic commented Jul 24, 2025

Uh oh!

read-the-docs-community Bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

read-the-docs-community Bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

yarikoptic commented Jul 24, 2025

Uh oh!

humitos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

humitos Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

humitos Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

humitos commented Jul 25, 2025

Uh oh!

humitos Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

humitos Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

yarikoptic Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yarikoptic commented Mar 7, 2024 •

edited

Loading

Configuration & Infrastructure (`20efc84`)

Ambiguous Typo Fixes (`f217b0b`)

Non-ambiguous Typo Fixes (`4c99a8e`)

read-the-docs-community Bot commented Jul 24, 2025 •

edited

Loading

read-the-docs-community Bot commented Jul 24, 2025 •

edited

Loading