GitLab CI/CD と Textlint で Markdown 形式の技術文書を自動的に校正する
この記事のまとめ：
- 文書校正ツールの textlint とそのプラグインの概要を紹介します。
- textlint を使える Dockerfile と GitLab CI のサンプルコードを紹介します
背景
GitLab CI/CD が簡単に使えて便利だということにいまさらながらに気付きまして、お試し的に身近なところの自動化をやってみようとという試みのひとつです。それとは別に、ちゃんと文書として何かを残しておく重要性を日に日に感じるようになってきました。その文書の管理に Git を使うと更新履歴も残してくれたり、共同作業も楽です。ついでに校正まで手軽にできたら便利だなということで、GitLab CI/CD と Textlint で校正をやってみようと至りました。ついでにこのブログの文書も校正をちゃんとしていなかったのでやっていきます。
文書校正ツール
今回使うメインの文書校正ツールは textlint です。textlint は主に日本語用のプレーンテキストと Markdown 用の静的解析ツールです。蛇足として、基本的には上記のフォーマットのファイル用の文書校正ツールなのですが、カスタムプラグインによって LaTeX などそれら以外のさまざまなフォーマットにも対応できるようです。
さらに、prh (proofread-helper) というツールも使います。 prh (proofread-helper) は公式には「校正を手伝ってくれるライブラリー」とざっくり説明されていますが、辞書ベースの表記ゆれを検出してくれるライブラリーです。検出したい表記ゆれの辞書を簡単に定義できるようになっています。もともとは Node.js 用のライブラリーですが、 textlint のプラグインとして textlint-rule-prh というものあります。今回は textlint をベースに使うのでこのプラグインを使います。
textlint の校正ルール
textlint は Collection of textlint rule に定義されている textlint-rule を設定することで自分好みの校正ルールを作成できます。また、それらのルールを組み合わせたプリセットもいくつか用意されているので手軽に使うにはプリセットを有効化することが手っ取り早いです。インストール方法や使用例はプリセットのページに記載されていますのでここでは割愛します。
主に技術文書向けに使うプリセットとしては次のようなものがあります。
prh 用辞書
prh 用辞書を自分で作成しなくてもいくつか準備して公開されているものがあります。まずはこういったものを適用して自分好みに修正すればよいです。公開されている辞書として次のようなものがあります。
サンプルファイル
サンプルとして用意したファイル類は私の GitLab リポジトリーである次のリンク先においておきました。
GitLab CI を使う前提ですので、Docker コンテナーで textlint を動かします。そのための textlint/Dockerfile やローカルでの動作確認を行うための docker-compose.yml が含まれています。
test-xxx のディレクトリーにはテスト用に次の設定で動かすためのファイルがそれぞれのディレクトリーに含まれています。
また、テスト用の文章として、Wikipedia の「校正」ページに記載されている概要の文章を test-xxx/fail.md として保存しています。
サンプルファイルの実行とテスト結果
それぞれローカルでテストするコマンドとその結果は次のようになります。なお、次の結果はそれぞれ校正チェックをするだけの実行ですが、--fix オプションをつけると、文字ゆらぎなどの一意に修正できるエラーについては自動で修正してくれます。
$ docker-compose run --rm textlint-ja-technical-writing textlint fail.md /work/fail.md 3:52 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 3:155 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 3:190 error Line 3 sentence length(124) exceeds the maximum sentence length of 100. Over 24 characters ja-technical-writing/sentence-length 3:219 error 一文に二回以上利用されている助詞 "か" がみつかりました。 ja-technical-writing/no-doubled-joshi 3:261 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 3:347 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 7:44 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 7:150 error 漢字が7つ以上連続しています: 劇作家福地桜痴 ja-technical-writing/max-kanji-continuous-len ✖ 8 problems (8 errors, 0 warnings)
$ docker-compose run --rm textlint-ja-engineering-paper textlint fail.md /work/fail.md 1:4 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:15 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:29 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:61 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:87 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:119 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:123 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:157 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:185 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 1:209 ✓ error 文末が"．"で終わっていません。 ja-technical-writing/ja-no-mixed-period 1:209 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:7 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:23 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:52 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:52 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 3:73 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:79 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:86 ✓ error かっこの外側、内側ともにスペースを入れません。 jtf-style/3.3.かっこ類と隣接する文字の間のスペースの有無 3:109 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:112 ✓ error 原則として、全角文字と半角文字の間にスペースを入れません。 jtf-style/3.1.1.全角文字と半角文字の間 3:119 ✓ error 原則として、全角文字と半角文字の間にスペースを入れません。 jtf-style/3.1.1.全角文字と半角文字の間 3:122 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:137 ✓ error 喩え => たとえ ja-engineering-paper/prh 3:142 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:155 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:155 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 3:164 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:189 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:190 error Line 3 sentence length(124) exceeds the maximum sentence length of 100. Over 24 characters japanese/sentence-length 3:194 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:219 error 一文に二回以上利用されている助詞 "か" がみつかりました。 ja-technical-writing/no-doubled-joshi 3:235 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:261 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:261 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 3:313 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:319 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:347 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 3:353 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:363 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:384 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 3:412 ✓ error 文末が"．"で終わっていません。 ja-technical-writing/ja-no-mixed-period 3:412 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:18 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:30 ✓ error かたち => 形 ja-engineering-paper/prh 5:38 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:55 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:71 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:75 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:82 ✓ error ひらがなで表記したほうが読みやすい形式名詞: 時 => とき ja-engineering-paper/ja-hiragana-keishikimeishi 5:95 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:111 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:119 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:147 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 5:160 ✓ error の他の => のほかの ja-engineering-paper/prh 5:180 ✓ error 文末が"．"で終わっていません。 ja-technical-writing/ja-no-mixed-period 5:180 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:4 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:19 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:44 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:44 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 7:60 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:88 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:111 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:139 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:144 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:167 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:186 ✓ error 頃 => ころ ja-engineering-paper/prh 7:187 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten 7:225 ✓ error 句読点には「，」と「．」を使用してください． ja-engineering-paper/unify-kuten-and-touten ✖ 69 problems (69 errors, 0 warnings) ✓ 62 fixable problems. Try to run: $ textlint --fix [file]
- prh に上で紹介した辞書を使ったときの結果
$ docker-compose run --rm textlint-prh textlint fail.md /work/fail.md 3:137 ✓ error 喩え => たとえ prh 5:30 ✓ error かたち => 形 prh 5:160 ✓ error の他の => のほかの prh 7:186 ✓ error 頃 => ころ prh ✖ 4 problems (4 errors, 0 warnings) ✓ 4 fixable problems. Try to run: $ textlint --fix [file]
GitLab CI
GitLab CI を動かすための .gitlab-ci.yml では、次の３つを行います。
- textlint そのもののテスト
textlint-test - textlint 用の Docker コンテナーのビルドを行い、同プロジェクトの container registry に登録
docker-push - ビルドしたコンテナーを使って textlint のテスト
docker-textlint-test
文書の校正だけを行うのであれば 3. の記述をコピーして使いまわせばよいです。
参考記事
- textlintのdocker imageを作ってgitlab-ciでCIする
- textlint + prhで文章を校正する方法
- Lint, Lint and Away! Linters for the English Language
今回は以上です。 最後まで読んでいただき、ありがとうございます。
コメント
コメントを投稿