Travis CI + RedPen で reST ドキュメントを継続的検査する

日時:2017/08/12
作者:moco_beta

概要

ドキュメント自動検査(校正)ツールRedPenを使い、GitHub で管理している reST ドキュメントの自動検査をTravis CIのジョブで走らせる方法を紹介します。

RedPen バージョン 1.9.0 で reST パーサが導入されたため、RedPen 1.9.0 以上を使用してください。

リポジトリのディレクトリ構成

ここでは、下記の Python プロジェクトを想定します。ソフトウェアのソースコードと一緒に、英語と日本語のドキュメントが同梱されているとします。

.
├── .travis.yml       // Travis CI 設定ファイル
├── docs
│   ├── en            // 英語ドキュメント
|   |   ├── conf.py
|   |   └── index.rst
│   ├── ja            // 日本語ドキュメント
|   |   ├── conf.py
|   |   └── index.rst
│   └── redpen        // RedPen 関連ファイル
|       ├── logback.xml
|       ├── redpen-conf-en.xml
|       └── redpen-conf-ja.xml
├── setup.py
└── source            // プログラムのソースコード

RedPen のルール設定ファイルを作成

まず、RedPen のルール設定ファイルを作成します。英語用と日本語用で設定が異なるため、それぞれについて設定ファイルを用意します。reST 特有の設定などはとくにありません。

non-Java プロジェクトの Travis ジョブに Java 8 を組み込む

RedPen は Java 8 で動作するため,コンテナ環境に Java 8 がインストールされている必要があります。

language: pythonのように、languagejava:8以外を指定しているプロジェクトでは、以下の Addon を.travis.ymlに追記することで java 8 のプログラムを動かせるようになります。

addons:
  apt:
    packages:
      - oracle-java8-set-default

(参考)Use JRE 8 on non-java project

Travis ジョブから RedPen を実行する

基本的にはこちらの記事RedPenを利用した文書の継続的検査への取り組みに書いてある流れと一緒です。ただし、ここではドキュメント検査のエラーでジョブは失敗させたくないので、本体のビルド成功後に実行されるafter_successで RedPen を走らせるようにします。

env:
  - REDPEN_VERSION=1.9.0
after_success:
  - wget -q https://github.com/redpen-cc/redpen/releases/download/redpen-${REDPEN_VERSION}/redpen-${REDPEN_VERSION}.tar.gz
  - tar xzf redpen-${REDPEN_VERSION}.tar.gz
  - cp docs/redpen/logback.xml redpen-distribution-${REDPEN_VERSION}/conf/logback.xml
  - redpen-distribution-${REDPEN_VERSION}/bin/redpen -c docs/redpen/redpen-conf-ja.xml -f rest docs/ja.rst
  - redpen-distribution-${REDPEN_VERSION}/bin/redpen -c docs/redpen/redpen-conf-en.xml -f rest docs/en.rst

この中で、カスタマイズした logback の設定ファイルをコピーしていますが,ログレベル等を調整する必要がなければ不要です。

まとめると.travis.yml全体は、以下のようになるでしょう。

language: python
python:
  - "2.7"
  - "3.3"
  - "3.4"
  - "3.5"
  - "3.6"
addons:
  apt:
    packages:
      - oracle-java8-set-default
env:
  - REDPEN_VERSION=1.9.0
script:
  - python setup.py test
after_success:
  - coveralls
  - wget -q https://github.com/redpen-cc/redpen/releases/download/redpen-${REDPEN_VERSION}/redpen-${REDPEN_VERSION}.tar.gz
  - tar xzf redpen-${REDPEN_VERSION}.tar.gz
  - cp docs/redpen/logback.xml redpen-distribution-${REDPEN_VERSION}/conf/logback.xml
  - redpen-distribution-${REDPEN_VERSION}/bin/redpen -c docs/redpen/redpen-conf-ja.xml -f rest docs/ja/index.rst
  - redpen-distribution-${REDPEN_VERSION}/bin/redpen -c docs/redpen/redpen-conf-en.xml -f rest docs/en/index.rst

検査結果

検査結果は、ジョブのログから確認できます。以下のようなドキュメント検査結果がログが出力されるはずです。

../../_images/travis-log.png