Wercker で Sphinx ドキュメントをコンパイルする

# 概要
[![English](https://img.shields.io/badge/English-here-lightgrey.svg?style=flat)](https://www.jkawamoto.info/blogs/sphinx-on-wercker/)
Wercker で Sphinx ドキュメントをコンパイルするための設定をスクリーンショット付きでまとめる．

# 手順
Wercker の Create → Application から対象のリポジトリをインポートする．
インポート後の画面は下記のようになっているので，`Workflow` タブへ移動する．

<img width="1331" alt="2016-08-18-1.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/c22762ab-f553-e4c8-0570-633949e124fd.png">

その中から `build` パイプラインの設定を開く．

<img width="1356" alt="2016-08-18-2.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/7992613d-974e-a59e-54f0-1f2def1f6fb4.png">

`build` パイプラインの設定画面をスクロールし，`Permission level` 項目を表示させる．

<img width="1334" alt="2016-08-18-3.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/621743e5-2a55-76d3-418b-24bb3b49532c.png">

そして，`Permission level` は，他人がパイプラインを実行することを防ぎ，
また不用意にログを公開しないように`execute pipeline` を選ぶ．
また，`Ignore branches` に `gh-pages`を追加しておく．
これを忘れると，ドキュメントを `gh-pages` に push 後，またコンパイルが始まってしまう．

<img width="1322" alt="2016-08-18-4.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/f7ab7946-2681-b830-d284-21188d26eea1.png">

次に，ワークフロータブへ戻り，新しいパイプラインを作成する．
<img width="1361" alt="2016-08-18-5.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/9c99dad2-0c46-f852-2c58-03ed3206cea5.png">

新しいパイプラインに `deploy` という名前をつけて，フックタイプをデフォルトにする．デフォルトは，前のパイプラインに繋げて使うための設定である．

<img width="1328" alt="2016-08-18-6.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/37ce7103-9fe1-00de-f8a1-554a4152f674.png">

コンパイルしたドキュメントを GitHub へアップロードするために，
このパイプラインへ GitHub へのアクセストークンを環境変数として登録する．
環境変数名は `GIT_TOKEN` とし，`protected` オプションにチェックを入れる．

<img width="1346" alt="2016-08-18-7.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/e4d2f25f-2a72-6e77-17ea-fcc1bf237b50.png">

GitHub のトークンは https://github.com/settings/tokens から取得できる．
公開リポジトリの場合は，`public_repo` にのみチェックを入れれば良い．
非公開リポジトリの場合は，`repo` にチェックを入れる必要があると思われる（試していない）．

<img width="1038" alt="2016-08-18-8.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/f9ec261a-d1f9-1ce6-3f3e-c14801e601d4.png">

`GIT_TOKEN` 環境変数を追加したら，Permission level を Execute pipelines に変更しパイプラインを作成する．

<img width="1337" alt="2016-08-18-9.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/ae2f865b-0e04-c0c4-de3f-36d507ddafdd.png">

次に，先ほど作成した `deploy` パイプラインを `build` に繋げて新しいワークフローを作成する．
また，master に push した時だけ動作するように， On branch(es) を編集しておく．

<img width="1342" alt="2016-08-18-10.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/f62943c1-afee-f55e-c350-b8c5f12bc282.png">

最終的に，次のようになっていれば良い．

<img width="1320" alt="2016-08-18-11.png" src="https://qiita-image-store.s3.amazonaws.com/0/62253/121899aa-acc1-e5ee-5159-6fcb13a22ee7.png">

最後に，`wercker.yml` をリポジトリに追加する．
例えば，`docs` フォルダにあるソースを Sphinx でコンパイルする場合，`wercker.yml`は次のようになる．


```wercker.yml
box: jkawamoto/ghp-box
build:
  steps:
    - jkawamoto/sphinx:
        basedir: docs
        packages: sphinx_rtd_theme
deploy:
  steps:
    - jkawamoto/ghp-import:
        token: $GIT_TOKEN
        basedir: docs/build/html
```

なお，この例では，`sphinx_rtd_theme` を利用し，
コンパイル後のドキュメントが `docs/build/html` に生成されると仮定している．
そうでない場合は，`basedir` を環境に合わせて編集する．

box や step の説明は下記を参照のこと．

- [jkawamoto/ghp-box](https://github.com/jkawamoto/dockerfiles/tree/master/wercker-ghp-box)
- [jkawamoto/sphinx](https://github.com/jkawamoto/wercker-sphinx-step)
- [jkawamoto/ghp-import](https://github.com/jkawamoto/wercker-ghp-import-step)