... | ... | @@ -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
|
|
|
when making changes.
|
|
|
|
|
|
We currently only lint Markdown syntax, with [markdownlint][]. You
|
|
|
can install it using the upstream instructions, but anarcat prefers to
|
|
|
run it under Docker, with a wrapper script like:
|
|
|
We currently lint Markdown syntax (with [markdownlint][]) and spell
|
|
|
check with [codespell][].
|
|
|
|
|
|
### 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
|
|
|
|
... | ... | @@ -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)
|
|
|
```
|
|
|
|
|
|
### 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
|
|
|
|
|
|
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. |
|
|
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
|
|
|
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
|
|
|
|
... | ... | @@ -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
|
|
|
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...
|
|
|
|
|
|
### Must have
|
... | ... | @@ -677,20 +689,23 @@ to add a `body:` tag on top and renamed to `.lr`. |
|
|
|
|
|
### Testing
|
|
|
|
|
|
To use those tests, we'd need to switch the wiki into a Git
|
|
|
repository, as it is not (currently) possible to run CI on changes in
|
|
|
GitLab wikis.
|
|
|
To use those tests, wikis need to be backed by a GitLab project (see
|
|
|
[Accepting merge requests on wikis](howto/gitlab#accepting-merge-requests-on-wikis)), as it is not (currently)
|
|
|
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:
|
|
|
* runs the [nodejs markdownlint][]: checks that Markdown syntax
|
|
|
* runs [vale][]: grammar, style, and word usage linter for the
|
|
|
English language
|
|
|
* 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
|
|
|
check documentation ([lefthook](https://github.com/evilmartians/lefthook), [precious](https://github.com/houseabsolute/precious), and
|
|
|
[pre-commit](https://pre-commit.com/) are similar wrappers)
|
|
|
* [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
|
|
|
* [anorack](https://github.com/jwilk/anorack): spots errors based on phonemes
|
|
|
* [redpen](https://redpen.cc/): huge JAR, can be noisy
|
... | ... | @@ -698,7 +713,9 @@ GitLab wikis. |
|
|
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))
|
|
|
* [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
|
|
|
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 |
|
|
features. Notably, it can warn about Kramdown compilation errors, for
|
|
|
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/
|
|
|
[nodejs markdownlint]: https://github.com/DavidAnson/markdownlint
|
|
|
[codespell]: https://github.com/codespell-project/codespell/
|
|
|
|
|
|
### Charts
|
|
|
|
... | ... | |