My External Storage

Jun 22, 2019 - 7 minute read - Comments - ci review circleci

textlint/reviewdogで文書校正エラーをGitHubのプルリクエストにコメントする 2019年6月版

技術書典7に向けて、執筆用のRe:VIEWのリポジトリの準備を始めた。
今回はCircleCIを使って文書校正を行なう設定を行なった。
検索して出てくる情報は古い情報が多かったので2019年6月時点の設定方法をまとめる。

TL;DR

  • Re:VIEW用の設定をしてPDFがビルドできる状態にする。
  • 文書の校正を行うtextlintの設定を行う
  • CircleCI上でreviewdogを使ってtexlintの結果をPull Request（PR）にコメントする
    • v0.9.12からインストール方法が変更されている。

サンプルリポジトリと実際にreviewdog経由でtextlintの指摘をコメントしたPRは以下になる。

同人誌作成もCIを使って自動化したい

私は今まで2回golang.tokyoとして技術書典に参加していた。
前回まではGitHub上で原稿（Re:VIEWファイル）を管理し、寄稿メンバー同士でPRを作って相互レビューをしていた。
CI的な設定はせずにもろもろを手作業で行なっていたが、今回はなるべく自動化したいと考えた。
そのため、まずは校正を自動で確認できるようにtextlintを使った自動化を試みた。

Re:VIEWのリポジトリを作成する

まずは新規のRe:VIEWリポジトリを作成する。ここから最新版の構築済みRe:VIEW構成を取得する。

サンプルのPDFファイル以外を使わせてもらう。

texlintrcを設定してローカルで文書校正できることを確認する

textlintは種々の静的解析ツールのように文書に対して文法や用語の使い方をチェックするツールだ。
プラグインを使えば、Re:VIEWの文書ファイルにも適用することができる。

まずは、CIの設定をする前にローカルで実行を確かめる。今回の設定は以下の記事を参考にした。

設定と言っても、npmコマンドで必要ライブラリをインストールしたあと、.textlintrcファイルを作成して校正ルールを設定すればよい。
どんなルールのオプションライブラリがあるのかは、GitHubのWikiを見る。

今回はRe:VIEWでtextlintを使うためのtextlint-plugin-reviewと技術書を書くための基本的なライブラリを使う。
用語の表記ゆれのチェックを行うtextlint-rule-prhライブラリは明示的にインストールしなくても使えるようだ（？）。

2019/06/23追記 textlint-rule-prhも明示的にインストールしておいたほうがよいと@azuさんからご指摘いただいた。
現状はtextlint-rule-preset-ja-technical-writingが内部で依存しているので暗黙的に利用できているだけとのこと。

$ npm install --save-dev textlint \
    textlint-rule-preset-ja-technical-writing \
    textlint-plugin-review \
    textlint-rule-prh

次に設定ファイルを作成する。リポジトリルートに.textlintrcファイルを以下のような内容で作成した。
textlint-rule-preset-ja-technical-writingは複数の校正ルールを内包しており、個別にルールのON/OFFを設定できる。

{
    "rules": {
        "preset-ja-technical-writing": {
            "no-exclamation-question-mark": false,
        },
        "prh": {
            "rulePaths": [
                "./prh-rules/media/WEB+DB_PRESS.yml"
            ]
        }
    },
    "plugins": [
      "review"
    ]
}

.textlintrcファイルを作成したあとは、適当なsample.reファイルをarticlesディレクトリに作成しtextlintコマンドを実行してみる。

$ ./node_modules/.bin/textlint articles/sample.re

/Users/budougumi0617/go/src/github.com/budougumi0617/shoten-plate/articles/sample.re
   3:4   ✓ error  はじめ => 始め                                                                                                                                                prh
  10:15  ✓ error  することができ => でき                                                                                                                                        prh
  10:15  ✓ error  "することができるはず"は冗長な表現です。"することが"を省き簡潔な表現にすると文章が明瞭になります。参考: http://qiita.com/takahi-i/items/a93dc2ff42af6b93f6e0  ja-technical-writing/ja-no-redundant-expression
  12:1   ✓ error  DockerHub => Docker Hub                                                                                                                                       prh
  12:25  ✓ error  ツイッター => Twitter                                                                                                                                         prh

✖ 5 problems (5 errors, 0 warnings)
✓ 5 fixable problems.
Try to run: $ textlint --fix [file]

意図通りに文書の表記ゆれなどが指摘された。

reviewdogとCircleCIを使ってPRに対してtextlintの検出エラーをコメントするようにする。

ローカルで実行が確認できたので、GitHubでPRを作成した時に、textlintのエラーをコメントで指摘するようにする。
reviewdogは各種静的解析ツールの結果をコードレビューコメントとしてPRなどにコメントしてくれるツールだ。textlintにも対応している。

reviewdogとCircleCIを使ってCIを構築する。reviewdogの使い方はREADMEの該当機能の説明を読めばよい。

利用するバージョンは2019/06/22現在最新のv0.9.12を使う。

CircleCIの設定は次のブログ記事を参考にした。

ただしこの記事は少し古く、最新のreviewdogの設定方法とは異なる。reviewdogのv0.9.12を使ってCircleCIの設定を行なうと次のようになる。

version: 2
jobs:
  build:
    docker:
      - image: vvakame/review:3.1
        environment:
          REVIEWDOG_VERSION: 0.9.12
    steps:
      - checkout
      - restore_cache:
          keys:
            - npm-cache-{{ checksum "package-lock.json" }}
      - run:
          name: Setup
          command: npm install
      - save_cache:
          key: npm-cache-{{ checksum "package-lock.json" }}
          paths:
            - ./node_modules
      - run:
          name: install reviewdog
          command: "curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh| sh -s  v$REVIEWDOG_VERSION"
      - run:
          name: lint
          command: "$(npm bin)/textlint -f checkstyle articles/*.re | tee check_result"
      - run:
          name: reviewdog
          command: >
              if [ -n "$REVIEWDOG_GITHUB_API_TOKEN" ]; then
                cat check_result | ./bin/reviewdog -f=checkstyle -name=textlint -reporter=github-pr-review
              fi              
          when: on_fail
      - run:
          name: Build PDF
          command: npm run pdf
      - store_artifacts:
          path: ./articles/shoten7.pdf
          destination: shoten7.pdf

あとはCircleCI上の設定をいくつかすればよい。

CircleCI上でCIを行なう準備をする

CircleCIで行う設定は、（対象のリポジトリへのビルドをONにするのは当然として、）reviewdogがPRへコメントをするときに利用するGitHubトークンの設定と、Only build pull requestsの設定だ。

reviewdogがPRへコメントできるようにCircleCiにGitHubトークンを設定する

reviewdogがPRへtextlintの検出エラーをコメントするために必要な認証情報をCirccleCIの環境変数に登録しておく。

Public/Privateリポジトリで必要な権限は異なるので、READMEをよく読むこと。

Go to https://github.com/settings/tokens and generate new API token. Check repo for private repositories or public_repo for public repositories.

GitHubでトークンを払い出したら、REVIEWDOG_GITHUB_API_TOKENという名前でCircleCIの環境変数にしておく。

  • Environment Variables | CircleCI
    • https://circleci.com/gh/YOUR_ACCOUNT/YOUR_REPO/edit#env-vars

Only build pull requests設定を有効にしておく

PRを作ったときにCircleCIが反応するようにしておかないと、コミットをプッシュした時点でCircleCIが反応し、reviewdogがうまく動かない。
PRとデフォルトブランチへのプッシュにのみ反応するようにCircleCIのOnly build pull requests設定を有効にしておく。

以上の設定をすべて完了して作成したPRが次のPRだ。

意図通り、PRにreviewdogからtextlintで検出したエラーがコメントされた。

reviewdog_comment

終わりに

他の方の記事を真似して設定すればすぐ終わると思っていたが、一部の環境構築の方法が最近変更されていたようなので、2019年版の設定方法をまとめた。
reviewdogのコメント用に払い出したトークンが自分のアカウントなので、自分が指摘しているようになってしまったがここはしょうがないかなと思う。
textlintの設定はまだ動作確認状態なので、もう少しチューニングしておきたい。あとはPRが作成されたらそのビルド結果のPDFをGoogleDriveに自動アップロードするCIを設定しておきたい。

参考

関連記事