第2章　便利なツールを使ってみよう！

せっかくRe:VIEWで本を書くのなら、周辺の便利なツールについても役立てたいところです。

本章では執筆に使ったツールを紹介します。

2.1　textlint

textlint*1はテキストファイルやマークダウンの校正ツールです。表記ゆれや長過ぎる文章、繰り返し表現などを検出することができ、これらの指摘を修正することでより良い文章へ修正することができます。

[*1] https://github.com/textlint/textlint

類似のツールにRedPen*2があります。また表記ゆれを検出できるツールにproofread-helper*3があり、こちらはtextlint-rule-prh*4経由でtextlintから使用することができます。

[*2] http://redpen.cc/

[*3] https://github.com/prh/prh

[*4] https://github.com/textlint-rule/textlint-rule-prh

textlintはプラグインを使用してルールの追加や入力フォーマットの追加が行えるようになっています。

今回は技術文書向けのルールをまとめたtextlint-rule-preset-ja-technical-writing*5を使用します。またRe:VIEW形式に対応するため、textlint-plugin-review*6も使用します。

[*5] https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing

[*6] https://github.com/orangain/textlint-plugin-review

これらのツールセットアップはnpmで行うのですが、ボイラープレートには既に導入済みです。bin/lintでtextlintでの校正を実行することができます。

$ bin/lint
yarn run v0.27.5
$ yarn --pure-lockfile && textlint src/*.re
Done in 9.29s.

もし校正で問題が検出された場合、以下のように問題のある箇所と指摘内容が表示されます。

$ bin/lint
yarn run v0.27.5
$ yarn --pure-lockfile && textlint src/*.re

/work/src/chapter02.re
  27:42  ✓ error  文末が"。"で終わっていません。  preset-ja-technical-writing/ja-no-mixed-period

✖ 1 problem (1 error, 0 warnings)
✓ 1 fixable problem.
Try to run: $ textlint --fix [file]

error Command failed with exit code 1.

ルールごとの設定は.textlintrcファイルに記述します。プリセットはかなり厳しく校正を行うため、書籍の特性に応じて緩めて使用するといいでしょう。

本書で使っている設定を以下に示します。

{
  "plugins": [
    "review"
  ],
  "filters": {
    "whitelist": {
      "allow": ["文字以上連続"]
    },
    "comments": true
  },
  "rules": {
    "preset-ja-technical-writing": {
      "no-exclamation-question-mark": false,
      "ja-no-weak-phrase": false
    }
  }
}

filtersには校正を無視するためのフィルタールールを設定します。

whitelistは単語単位で校正を無視するためのものです。例えば漢字が6文字以上連続しないというルールで「文字以上連続」という部分だけは無視したい、という場合にこのような設定を行います。

commentsはコメントで校正を無視する文章の指定を行えるものです。#@# textlint-disableと#@# textlint-enableで挟んだ箇所を校正対象外とします。

rulesには校正ルールの設定を記述します。

この本では、！や？を使わないようにするno-exclamation-question-markルールと、「思います」などの弱い表現を使わないja-no-weak-phraseを無効にしています。

2.2　CircleCI

せっかく文章校正をコマンドで行えるのなら、自動で流したくなりますよね。CircleCI@<fn>[circleci]を使って自動で校正を行うようにしましょう。

[*7] https://circleci.com/

まずはGitHubリポジトリを作り、原稿をpushする必要があります。新規リポジトリを作成した上でgitリポジトリのoriginに設定しましょう。

以下は本書の例ですので、git urlを新しく作ったリポジトリのものに変えて実行してください。

$ git remote add origin git@github.com:kokuyouwind/review-review.git
$ git push origin master

このリポジトリに対してCircleCIを設定しましょう。ボイラープレートでは既に設定ファイルが存在するので、CircleCIからプロジェクトを作成するだけでOKです。

CircleCIにログインし、「Add Proejct」からプロジェクトを追加します。プロジェクトを追加すると、自動でビルドが始まり校正と書籍ファイルの作成が行われるようになります。

ビルドに成功すると、図2.1のようにArtifactが生成され、PDFなどを確認することができます。

図2.1: CircleCIでのArtifact生成

CircleCIの設定は.circleci/config.ymlに記述されています。追加のテストなどを行いたい場合はこのファイルを編集してください。

2.3　reviewdog

textlintの結果を確認するためにいちいちCircleCIの画面を見るのは面倒ですね。

reviewdog*8を使うと、校正内容をGitHubのプルリクエストにコメントで書き込んでくれます。

[*8] https://github.com/haya14busa/reviewdog

.circleci/config.ymlで既にreviewdogを使うよう設定されているため、CircleCIのプロジェクトに以下を設定するだけで使えるようになります。

https://github.com/settings/tokens からGitHubアクセストークンを発行する
CircleCIのプロジェクト設定で、BuildSetting > Environment Variablesから環境変数を設定する
- REVIEWDOG_GITHUB_API_TOKENに先ほど発行したGitHubアクセストークンを設定する
同じくプロジェクト設定で、Advanced Settings > Only build pull requestsを有効にする

これらの設定を行った上で、textlintに違反したコードを含むプルリクエストを作成すると、図2.2のようにプルリクエストコメントで指摘が行われます。

図2.2: reviewdogでの指摘コメント

第2章 便利なツールを使ってみよう！

2.1 textlint

2.2 CircleCI

2.3 reviewdog

第2章　便利なツールを使ってみよう！

2.1　textlint

2.2　CircleCI

2.3　reviewdog