はじめに
日本語が苦手なみなさんこんにちは。
開発ドキュメントもgithub/gitlabで管理されているひとも多いでしょう。うちのチームでもドキュメントレビューをgitlabのmerge requestで実施しています。
ただ、そういったレビューをしている中、隣の新人くんから「日本語の指摘が多い。。。」「自動検出したい。。。」という声が聞こえてきたので、textlintを導入してみました。
textlintとは
nodejs製の文章校正ツールです。
どうやって使うのか
Docker imageを作りました。
referenceにあるように参考にさせていただき、ほぼ同じようなものを作りました。DockerHubを使う練習がてら作ってみました。しかし便利ですね、DockerHubは。。。Dockerあればどこでも同じことができる。
Docker環境がある方は以下の要領で簡単に使えます。
$ git clone <some repository>
$ cd <some repository>
$ docker run -v $(pwd):/data -w /data tk117/docker-textlint textlint <your file>
ただし、.textlintrcファイルがある場所で実行してください。このファイルがtextlintでどのルールを採用するかが書かれた設定ファイルです。後でciで使うためにもリポジトリにコミットしておくとよいでしょう。
{
"rules": {
"preset-ja-technical-writing": {
"no-exclamation-question-mark": false,
},
"preset-jtf-style": true,
"spellcheck-tech-word": true
}
}
エラーがなければ何も表示されません。
エラー例
この文章はsampleです。
確かに、sampleですが、サンプルなのですが、あえてミスをして、警告をもらうようにしています
上記の文章を実行すると、このような警告が行われます。
# docker run -v $(pwd):/data -w /data tk117/docker-textlint textlint sample.md
/work/sample.md
4:13 error 文中に逆接の接続助詞 "が" が二回以上使われています。 preset-ja-technical-writing/no-doubled-conjunctive-particle-ga
4:24 error 一つの文で"、"を3つ以上使用しています preset-ja-technical-writing/max-ten
4:47 ✓ error 文末が"。"で終わっていません。 preset-ja-technical-writing/ja-no-mixed-period
✖ 3 problems (3 errors, 0 warnings)
✓ 1 fixable problem.
Try to run: $ textlint --fix [file]
ちゃんと怒ってくれる！
今回採用したルール
まずは少なくはじめようと思い、以下の2つですね。
- preset-jtf-style
- spellcheck-tech-word
--fixで自動修正してくれるのはとてもうれしいですね。
CIに組み込む
うっかりルール違反したままpushしてしまったときのために、継続的にテストしたいですよね。
今回はgitlab-ciを使いました。
stages:
- lint
textlint:
image: tk117/docker-textlint
stage: lint
script:
- textlint <target path>
tags:
- sample-project
runner登録時にtagをつけたらそのtagを指定してください。簡単ですね！
ディレクトリ構成がキモになりますね。全部がドキュメントのプロジェクトであれば全部対象で良さそうですが、開発向け設計書の他にいろいろまとめて格納している場合はどういった運用になるか考える必要がありそうです。
対象が増えるたび.gitlab-ci.ymlを更新しないといけないのはイヤですね。そうしなくて済むようなディレクトリ構成にすべきだと思います。
エディタ
ローカルでdockerで簡単に実行できるとはいえ、dockerなんてしらなーい！ってひともいますよね。
Atom, sublime, vimにプラグインが用意されているようです。
おわりに
CIに組み込むことで過去のドキュメントも再帰的にテストができます。lintを通っていない文章はmergeできないようにしてもいいでしょう。
まだ使い始めたばかりなので、今後もたくさん使ってプロジェクトに合ったルールを採用していこうと思います。contributionもできたらいいな。