===============================================================
Travis CI + RedPen で reST ドキュメントを継続的検査する
===============================================================
:日時: 2017/08/12
:作者: moco_beta
概要
======
ドキュメント自動検査(校正)ツール `RedPen `_ を使い、GitHub で管理している reST ドキュメントの自動検査を `Travis CI `_ のジョブで走らせる方法を紹介します。
RedPen バージョン 1.9.0 で reST パーサが導入されたため、RedPen 1.9.0 以上を使用してください。
リポジトリのディレクトリ構成
=========================================
ここでは、下記の Python プロジェクトを想定します。ソフトウェアのソースコードと一緒に、英語と日本語のドキュメントが同梱されているとします。
.. code-block:: bash
.
├── .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 特有の設定などはとくにありません。
* 英語用の設定例: `redpen-conf-en.xml `_
* 日本語用の設定例: `redpen-conf-ja.xml `_
non-Java プロジェクトの Travis ジョブに Java 8 を組み込む
===================================================================
RedPen は Java 8 で動作するため,コンテナ環境に Java 8 がインストールされている必要があります。
``language: python`` のように、 ``language`` に ``java:8`` 以外を指定しているプロジェクトでは、以下の Addon を ``.travis.yml`` に追記することで java 8 のプログラムを動かせるようになります。
.. code-block:: yaml
addons:
apt:
packages:
- oracle-java8-set-default
(参考) `Use JRE 8 on non-java project `_
Travis ジョブから RedPen を実行する
=================================================
基本的にはこちらの記事 `RedPenを利用した文書の継続的検査への取り組み `_ に書いてある流れと一緒です。ただし、ここではドキュメント検査のエラーでジョブは失敗させたくないので、本体のビルド成功後に実行される ``after_success`` で RedPen を走らせるようにします。
.. code-block:: yaml
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`` 全体は、以下のようになるでしょう。
.. code-block:: yaml
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
検査結果
========
検査結果は、ジョブのログから確認できます。以下のようなドキュメント検査結果がログが出力されるはずです。
.. figure:: travis-log.png
:scale: 75