Changes

Page history
spell check the wiki with codespell authored by anarcat's avatar anarcat 
There's currently 176 spelling errors in the wiki, and there were some
in this very file (`service/documentation.md`), but I've fixed those
so CI passes here.

This also required (I think) renaming the `test` job to `mdlint`
otherwise we would be somewhat incoherent: the spell check job is also
a "test" job...
Show whitespace changes
Inline Side-by-side
service/documentation.md
View page @ 8a769f63
...@@ -96,9 +96,13 @@ While the wiki replica has continuous integration checks, it might be ...@@ -96,9 +96,13 @@ While the wiki replica has continuous integration checks, it might be
good to run those locally, to make sure you don't add any new warnings good to run those locally, to make sure you don't add any new warnings
when making changes. when making changes.
We currently only lint Markdown syntax, with [markdownlint][]. You We currently lint Markdown syntax (with [markdownlint][]) and spell
can install it using the upstream instructions, but anarcat prefers to check with [codespell][].
run it under Docker, with a wrapper script like:
### Markdown linting
You can install [markdownlint][] using the upstream instructions, but
anarcat prefers to run it under Docker, with a wrapper script like:
[markdownlint]: https://github.com/markdownlint/markdownlint [markdownlint]: https://github.com/markdownlint/markdownlint
...@@ -126,6 +130,14 @@ ${GIT_DIR:-.git}/../bin/mdl-wrapper $(git diff --cached --name-only HEAD) ...@@ -126,6 +130,14 @@ ${GIT_DIR:-.git}/../bin/mdl-wrapper $(git diff --cached --name-only HEAD)
${GIT_DIR:-.git}/../bin/mdl-wrapper $(git diff-tree --no-commit-id --name-only -r HEAD) ${GIT_DIR:-.git}/../bin/mdl-wrapper $(git diff-tree --no-commit-id --name-only -r HEAD)
``` ```
### Spell checking
The [codespell][] program checks for spelling mistakes in CI. If you
have a CI failure and you just want to get rid of it, try:
apt install codespell
codespell --write-changes $affected_file.md
## Accepting merge requests on wikis ## Accepting merge requests on wikis
It's possible to work around the [limitation of Wiki permissions](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/76) It's possible to work around the [limitation of Wiki permissions](https://gitlab.torproject.org/tpo/tpa/gitlab/-/issues/76)
...@@ -445,7 +457,7 @@ from running basic tests on the documentation. ...@@ -445,7 +457,7 @@ from running basic tests on the documentation.
This would require hooking up the wiki in GitLab CI, which is not This would require hooking up the wiki in GitLab CI, which is not
currently possible within GitLab wikis. We'd need to switch the wiki currently possible within GitLab wikis. We'd need to switch the wiki
to a full Git repository, possibly pushing to the wiki using a deploy to a full Git repository, possibly pushing to the wiki using a deploy
key on succesful runs. But then why would we keep the wiki? key on successful runs. But then why would we keep the wiki?
### Structure ### Structure
...@@ -539,7 +551,7 @@ is unlikely we will make any major change on the documentation system ...@@ -539,7 +551,7 @@ is unlikely we will make any major change on the documentation system
in the short term, unless one of the above issues becomes so critical in the short term, unless one of the above issues becomes so critical
it needs to immediately be fixed. it needs to immediately be fixed.
That said, improvements or replacements to the current sytem should That said, improvements or replacements to the current system should
include... include...
### Must have ### Must have
...@@ -677,20 +689,23 @@ to add a `body:` tag on top and renamed to `.lr`. ...@@ -677,20 +689,23 @@ to add a `body:` tag on top and renamed to `.lr`.
### Testing ### Testing
To use those tests, we'd need to switch the wiki into a Git To use those tests, wikis need to be backed by a GitLab project (see
repository, as it is not (currently) possible to run CI on changes in [Accepting merge requests on wikis](howto/gitlab#accepting-merge-requests-on-wikis)), as it is not (currently)
GitLab wikis. possible to run CI on changes in GitLab wikis.
* GitLab has a [test suite](https://docs.gitlab.com/ee/development/documentation/testing.html) for their documentation which: * GitLab has a [test suite](https://docs.gitlab.com/ee/development/documentation/testing.html) for their documentation which:
* runs the [nodejs markdownlint][]: checks that Markdown syntax * runs the [nodejs markdownlint][]: checks that Markdown syntax
* runs [vale][]: grammar, style, and word usage linter for the * runs [vale][]: grammar, style, and word usage linter for the
English language English language
* checks the internal anchors and links using Nanoc * checks the internal anchors and links using Nanoc
* [codespell][] checks for typos in program source code, but also
happens to handle Markdown nicely, it can also apply corrections
for errors it finds
* [Danger systems](https://danger.systems/ruby/) has a bunch of plugins which could be used to * [Danger systems](https://danger.systems/ruby/) has a bunch of plugins which could be used to
check documentation ([lefthook](https://github.com/evilmartians/lefthook), [precious](https://github.com/houseabsolute/precious), and check documentation ([lefthook](https://github.com/evilmartians/lefthook), [precious](https://github.com/houseabsolute/precious), and
[pre-commit](https://pre-commit.com/) are similar wrappers) [pre-commit](https://pre-commit.com/) are similar wrappers)
* [textlint](https://textlint.github.io/): pluggable text linting approach recognizing markdown * [textlint](https://textlint.github.io/): pluggable text linting approach recognizing markdown
* [proselint](http://proselint.com/): grammar and style checkign * [proselint](http://proselint.com/): grammar and style checking
* [languagetool](https://www.languagetool.org/): Grammar, Style and Spell Checker * [languagetool](https://www.languagetool.org/): Grammar, Style and Spell Checker
* [anorack](https://github.com/jwilk/anorack): spots errors based on phonemes * [anorack](https://github.com/jwilk/anorack): spots errors based on phonemes
* [redpen](https://redpen.cc/): huge JAR, can be noisy * [redpen](https://redpen.cc/): huge JAR, can be noisy
...@@ -698,7 +713,9 @@ GitLab wikis. ...@@ -698,7 +713,9 @@ GitLab wikis.
maintainers), has many alternatives, see for example [lychee](https://github.com/lycheeverse/lychee), maintainers), has many alternatives, see for example [lychee](https://github.com/lycheeverse/lychee),
[muffet](https://github.com/raviqqe/muffet), [hyperlink](https://github.com/untitaker/hyperlink), [more](https://gitlab.torproject.org/tpo/tpa/ci-templates/-/issues/14#note_2843661)) [muffet](https://github.com/raviqqe/muffet), [hyperlink](https://github.com/untitaker/hyperlink), [more](https://gitlab.torproject.org/tpo/tpa/ci-templates/-/issues/14#note_2843661))
* [forspell](https://github.com/kkuprikov/forspell): wrapper for hunspell, can deal with (Ruby, C, C++) * [forspell](https://github.com/kkuprikov/forspell): wrapper for hunspell, can deal with (Ruby, C, C++)
source code, local dictionnaries source code, local dictionaries
See also [this LWN article](https://lwn.net/Articles/822969/).
Note that we currently use [markdownlint][], the Ruby version, not the Note that we currently use [markdownlint][], the Ruby version, not the
Node version. This was primarily because anarcat dislikes Node more Node version. This was primarily because anarcat dislikes Node more
...@@ -706,10 +723,14 @@ than Ruby, but it turns out the Ruby version also has more ...@@ -706,10 +723,14 @@ than Ruby, but it turns out the Ruby version also has more
features. Notably, it can warn about Kramdown compilation errors, for features. Notably, it can warn about Kramdown compilation errors, for
example finding broken Markdown links. example finding broken Markdown links.
See also [this LWN article](https://lwn.net/Articles/822969/). We also do basic spell checking with [codespell][] mostly because it
was simple to setup (it's packaged in Debian while, say, vale isn't)
but also because it has this nice advantage of supporting Markdown and
it's able to make changes inline.
[vale]: https://errata-ai.gitbook.io/vale/ [vale]: https://errata-ai.gitbook.io/vale/
[nodejs markdownlint]: https://github.com/DavidAnson/markdownlint [nodejs markdownlint]: https://github.com/DavidAnson/markdownlint
[codespell]: https://github.com/codespell-project/codespell/
### Charts ### Charts
... ...
......