Fix as many spelling mistakes as possible

[ernstki]

• adds a new dependency for spell checking as part of the Sphinx build process: sphinxcontrib-spelling
• adds two new Makefile targets: check-spelling and fix-spelling (fix-spelling works best with the Vim editor)

You can run the Make targets like this:

# interactively update local wordlist and open $EDITOR to fix misspellings
make spell && make fix

# skip updating the local wordlist with new (mis)spellings
make spell SKIP_ADD_SPELLINGS=1 && make fix

[ernstki]

As a reader of the docs, I noticed a few misspellings, but there ended up being more than I could fix by hand, so I went looking for tools to help. I started out using Vale, but decided on sphinxcontrib-spelling in the end, since the format of the config file (conf.py) is already familiar.

If you, the maintainers, are not happy with my use of sphinxcontrib-spelling's spelling:word-list directive to create per-file word lists, I'm happy to collapse all those into the top-level wordlist.txt instead.

It seemed inadvisable to do so with words that seemed likely to be actual misspellings or mis-capitalizations elsewhere, like sys and usb, which is why I didn't.

[jans23]

Thank you for your contribution. That approach is much appreciated. We will take a closer look soon and come back here.

[daringer]

I am impressed how many typos and spelling errors we've generated - thanks for the effort ... this really looks pretty good - could you please separate the implementation from the actual spelling fixes - then I'd say LGTM.

[ernstki]

I am impressed how many typos and spelling errors we've generated - thanks for the effort ... this really looks pretty good - could you please separate the implementation from the actual spelling fixes - then I'd say LGTM.

You all are writing code and building products and working in two languages, so no judgements from me. I'm happy to be able to help.

Is the "implementation" part actually a useful contribution (to submit as a second PR), or… should I simply elide those Makefile modifications altogether? No hard feelings either way.

[daringer]

Thanks, for the kind words :D
I don't think there is need for another PR, I'd just like to have a commit which I can easily identify which does the actual "implementation" (Makefile stuff, conf.py, req.txt ...) and one for the actual spelling fixes

[ernstki]

I'd just like to have a commit which I can easily identify which does the actual "implementation" (Makefile stuff, conf.py, req.txt ...) and one for the actual spelling fixes

@daringer OK, this is done.

I would welcome feedback about how useful you think the Vim parts will actually be. If no one on your team uses that editor, then those parts of the Makefile are probably just a maintenance liability.

The commit message for ac07841 describes the process I used. I have also updated the README (locally) with the same information, but I'll do that in a separate PR, once this is merged, if that's okay.

[daringer]

hey, for delaying this further - I am a big fan of the vim-workflow - would keep it for now!
could you resolve the current conflicts (and thus rebase) then I'd merge this right afterwards ?

[ernstki]

hey, for delaying this further - I am a big fan of the vim-workflow - would keep it for now! could you resolve the current conflicts (and thus rebase) then I'd merge this right afterwards ?

Yes, will do! I'll @-mention you again when it's ready, just in case GitHub doesn't send a distinctive enough notification.

[ernstki]

@daringer readysetgo!

These files had conflicts, if you wanted to scrutinize those specially, e.g., for bad formatting:

• source/components/nethsm/compatible/knotdns.rst
• source/components/nitrokeys/features/u2f/desktop-login.rst
• source/components/nitrokeys/nitrokey3/set-pins.rst
• source/components/nitrophone/apps.rst

Also, a minor point: you feel that replug and replugged are acceptable spellings for your team, just let me know and I'll update the word list and all affected documents. I have pedantically insisted on re-plug and re-plugged here; my take is they haven't been around long enough to become Real Dictionary Words in the sense that reiterate and reevaluate are.

For what it's worth, make check-hyperlinks also passes for me:

Statistics:
Downloaded: 38.8MB.
Content types: 325 image, 249 text, 0 video, 0 audio, 13 application, 0 mail and 6425 other.
URL lengths: min=15, max=884, avg=68.

That's it. 7012 links in 7012 URLs checked. 0 warnings found. 0 errors found.
Stopped checking at 2026-06-11 17:38:18-004 (2 minutes, 11 seconds)

[jans23]

I looked at the files you pointed out specifically and changed some in #591. Before merging we would need to fix the CI. @mmerklinger could you take a look at these CI errors, please?

[ernstki]

could you take a look at these CI errors, please?

@jans23 sorry! I definitely would've thought twice if I'd known sphinxcontrib-spelling would add a C library dependency. It is mentioned in their docs, but it's buried in the developer section.

[ernstki]

@mmerklinger Would you like me to simply omit sphinxcontrib-spelling from the main requirements.txt and not load that extension in source/conf.py by default?

I think it should be a simple matter to pass an option to conditionally add sphinxcontrib.spelling to the list of extensions in source/conf.py and regulate that with sphinx-build --define SPELL=1 or something like that.

This should allow CI to run successfully, and won't require the enchant library to be installed in the containers (although it should be possible with some well-placed run: apt update && apt install -y libenchant-2-2 lines in the CI config).

[mmerklinger]

@ernstki Thanks for your PR!

Would you like me to simply omit sphinxcontrib-spelling from the main requirements.txt and not load that extension in source/conf.py by default?

No, that should be fine. If you could add a note about the enchant dependency in the readme file under "Local build" would be great though.

Besides, please rebase the PR on the main branch.

I made some commits in a separate branch to include a job for spell checking in the CI pipeline. Also I "fixed" the rstcheck. You can either pick this commits on top of your branch, or I will create a separate PR after we merged yours. As you prefer.