RedPenを使って技術文書を手軽に校正しよう

第2回 RedPenを利用した文書の継続的検査への取り組み

この記事を読むのに必要な時間:およそ 4 分

RedPenをTravis上で動作させる

ではGitHubで管理されている文書に対してTravisを介して自動でRedPenを適用します。

利用するGitHubプロジェクト

例として使用する文書をGithubのレポジトリにおきました。レポジトリは次の構成となっています。

  • sampledoc-ja.md ー 検査対象のMarkdownフォーマット文書。
  • repden-conf-ja.xml ー RedPen の設定ファイル。content.md を検査する項目が列挙されています。
  • .travis.yml ー Travis の設定ファイル。RedPen を配備して,検査を実行する手順が記載されています。

Travisの設定

本プロジェクトで利用する.travis.ymlは,次のとおりです。

language: text

jdk:
  - oraclejdk8

env:
  - URL=https://github.com/recruit-tech/redpen/releases/download/v1.0-experimental-1

install:
  - wget $URL/redpen-cli-1.0-assembled.tar.gz
  - tar xvf redpen-cli-1.0-assembled.tar.gz

script:
  - redpen-cli-1.0/bin/redpen -c redpen-conf-ja.xml -f markdown -r xml sampledoc-ja.md

上記のファイルを見るとinstallブロックでRedPenパッケージをダウンロードし,scriptでRedPenを対象文書に適用しているのがわかります。詳しいTravisの文法についてはTravisのマニュアルを参照してください。またGitHubのプロジェクトをTravisでテストするには,プロジェクトをTravisに登録する必要もあります。

今回サンプルとして利用する文書sampledoc-ja.mdの内容は次のとおりです。実は文書にはいくつか悪い点が存在します。

# 分散処理
最近利用されているソフトウェアの中には複数の計算機上で動作(分散)するものが多く存在し,このような分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり,高負荷な状況に対処できたりします。
本稿では,複数の計算機(クラスタ)でで動作する各サーバーをインスタンスと呼びまます。
たとえば検索エンジンやデータベースではインデックスを複数のインスタンスで分割して保持します。
このような場合,各インデクスの結果をマージしてclientプログラムに渡す機構が必要となります。

この文書(sampledoc-ja.md)Githubのレポジトリにプッシュしたところ,Travisから報告が得られました。

Travis結果(一回目)

画像

Travisが出力したログのうち,次の行:

The number of errors "12" is larger than specified (limit is "1").

から,文書には12件のエラーが存在したことがわかります。ではエラーの内容を詳しく検査してみましょう。

エラー分析

まず2行目が長すぎるというエラーが出ています。また同じく2行目で,複数の単語⁠分散⁠⁠,⁠ソフトウェア⁠等が一文中に2回以上利用されているというエラーも出ています。これらのエラーは文が長すぎるために起こってしまっています。後ほど修正しましょう。

3行目で半角のカンマが利用されていることが報告されています。RedPenのデフォルト設定ではカンマは全角のものとなっているため,全角カンマを利用するか,シンボル設定を変更する必要があります。また3行目で,カタカナ単語⁠サーバー⁠の末尾長音が必要ないというエラーも出ました。KatakanaEndHyphn機能はJIS Z831にもとづいてカタカナ単語の末尾の使用の正しさを検査します。その他,3行目には(クラスタ)ででと助詞⁠で⁠が重なってしまっているという単純なミスも存在します。

5行目でアルファベット単語(client)の前後に半角スペースが存在しないというエラーが出力されました。これはSpaceBetweenAlphabeticalWord機能から出力されたエラーです。SpaceBetweenAlphabeticalWord機能はアルファベット単語の前後にスペースがあるかを検査してくれます。私は通常アルファベット単語の前後にスペースを入れるという規約にもとづいて文書を書きますが,ここでは入れるのを忘れてしまいました。ちなみに本稿(gihyo.jp)はアルファベット単語の前後にスペースを入れないという規約のため,文書内のスペースは取り除かれています。

エラーを修正する

では早速エラーを修正していきましょう。まず2文目が長すぎるためにエラーを出力されてしまっているのが気になります。2文目の文は次のとおりです。

最近利用されているソフトウェアの中には複数の計算機上で動作(分散)するものが多く存在し,このような分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり,高負荷な状況に対処できたりします。

この文は長すぎ,つまり多くの仕事を背負ってしまっています。そこで,次のように分割します。文を分割することで一文に⁠分散⁠⁠,⁠ソフトウェア⁠といった単語が2回利用されているというエラーも一緒に修正されます。

最近利用されているソフトウェアの中には複数の計算機上で動作(分散)するものが多く存在します。
分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり,高負荷な状況に対処できます。

第3文で利用されている半角カンマを全角に変更します。また,カタカナ単語⁠サーバー⁠の不正な長音を取り除きます。第5文ではアルファベット単語clientの前後スペースを追加します。

これらの修正を反映させた文書は次のとおりです。

# 分散処理
最近利用されているソフトウェアの中には複数の計算機上で動作(分散)するものが多く存在します。
分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり,高負荷な状況に対処できます。
本稿では,複数の計算機(クラスタ)で動作する各サーバをインスタンスと呼びまます。
たとえば検索エンジンやデータベースではインデックスを複数のインスタンスで分割して保持します。
このような場合,各インデクスの結果をマージして client プログラムに渡す機構が必要となります。

この内容をコミットした上で,GitHubにプッシュします。プッシュするとTravisが自動で動作します。Travisより送られてきた修正報告の内容から, 検査が無事パスしたことがわかりました。次図は結果の内容を一部キャプチャしたものです。

Travis結果(二回目)

画像

コラム:プルリクエストの活用

今回はサーバのmasterレポジトリにそのままプッシュしましたが,複数人数で執筆するときにはプルリクエストベースでレビューを徹底したいという組織も多いのではないかと思います。その場合には今回と同様の設定(.travis.yml)を追加した後,トピックブランチを作成しプルリクエストを送る形で執筆することでmasterレポジトリにマージされる前に文書の検査を行えます。

文書の継続的検査の今後

今回,RedPenとTravisを使って文書をプッシュするたびに検査が走る環境を作ってみました。しかし残念ながら未だ不満があります。Travisで利用した場合,今回使用した例のようにRedPenのリリースページからwgetやcurlコマンドでRedPenのパッケージをダウンロードする必要があります。結果的に.travis.ymlファイルが大きくなってしまいました。

今後はRedPenのサーバ機能(REST API)を強化し,URLと設定を指定しただけで簡単に検査が行えるように拡張していく予定です。

著者プロフィール

伊藤敬彦(いとうたかひこ)

ソフトウェアエンジニア。専門はデータマイニングと情報検索だが,他にも色々やってみたいと感じている。