JenkinsでビルドしたSphinxドキュメントを画面からリンクする

最近、俺の 過去日記 を読まれた方からこういう質問を受けたんです。

Jenkinsで"make html"したSphinxドキュメントをJenkinsのプロジェクトから見れるようにしたい。
(Doxygen プラグインみたいに)

その場では「あーわかんないっすｗ」みたいに答えたのですが、悔しかったんで調べて見ました。

相手が望んでるものって？

「Doxygenプラグインみたいに…」という言葉があったので「どんなものか」を調べました。

あ〜これ系かぁ…プラグインで作る系のアイコンですねと。

で、調べてみるに「Sphinxを冠したPluginは無さそう」でした。

ただ「Link(アンカー)を汎用的に張るくらい、何かあるんじゃねーか？」という線で当たりたいと思います。

置いた「望んでいる人像」前提

• 言語は問わない(JavaなんだかCなんだか)がJenkinsでビルドする
• そのプログラムのドキュメント(リリースノートとかなんとかDoc的なもの)はソースの一部としてVCSに入れてある
• そのドキュメントはSphinxで出来ている
• プログラムのビルド後、ドキュメントもビルドしてJenkinsのジョブトップからリンクで見たい

である、と。

なので「一個のJenkinsジョブの前半でプログラムをビルドし、後半でSphinxドキュメントをビルド」したいのだ、と考えます。

「フリースタイル・プロジェクトのビルド」でJenkinsジョブをつくれば、こんな感じ？

そこで必要な”sphinx-build”のコマンドについては、

• 自身でJenkinsサーバを弄える人は「インストールしてJenkinsのユーザから叩ける」状態
• それ以外の人は 過去日記 とかでジョブ中にて用意

なことを前提とします。

ジョブの「トップのページ」にワークスペース中の”在るファイル”のリンクを出す

まず「DocLinks Plugin」をインストールします。

次に、Sphinxをビルドするジョブの”設定”を開き、画面下部「ビルド後の処理の追加」から”ドキュメントの公開”を選んでください。

出てきた入力域に以下のように入力し、ジョブ自身を保存して下さい。

その後、一度でもビルドした後は、ジョブのトップのページに以下のようなリンクが現れます。

アイコンとか無いけど…ま、妥協という事でｗ

ビルドごとのSphinxドキュメントを保存しておく

これで「一回前のビルド時のShpnxドキュメント」は閲覧できるようになりました。

しかし、(上記で置いた前提では)Sphinxドキュメントもソースと連動して更新して行くと思われるので、「過去ビルドの”その時の”Sphinxドキュメント」が欲しいのではないかと思います。

そこで、ビルド毎に「Sphinxドキュメント一式を残す」ことにします。

Sphinxをビルドするジョブの”設定”を開き、画面下部「ビルド後の処理の追加」から”成果物の保存”を選んでください。

出てきた入力域に以下のように入力し、ジョブ自身を保存して下さい。

その後、一度でもビルドした後は、ジョブのトップのページに以下のように「最新成功ビルドの成果物」のリンクと”参照＋”のような、ツリーが追加されていると思います。

画面左下部の「ビルド履歴」から、過去のビルドを参照しても同じリンクとツリーが表示されており、ツリーを展開すると過去のドキュメントが参照できます。

少々不恰好ですが、これにて「過去のドキュメント」も参照可能になりました。

プログラムのビルドとSphinxドキュメントのビルドを切り離したい場合

上記「前提」で示したJenkinsジョブの例だと、プログラムもSphinxのビルドも両方とも「シェルの実行」で行うため、Sphinxのビルドで失敗すればジョブ自体が失敗となります。

また、

• プログラムのビルドはコケてもその時のSphinxドキュメントはビルドして取って置きたい
• 逆にSphinxドキュメントのビルドがコケてもジョブはコケて欲しくない

と考えるのが一般的だと思います。そこで…

「Sphinxビルドはプログラムのビルドが成功しようがしまいが行う後処理」

へと、扱いを変えます。

「Hudson post build task」をインストールします。

次に、Sphinxをビルドするジョブの”設定”を開き、画面下部「ビルド後の処理の追加」から”post build task”を選んでください。

出てきた入力域に以下のように入力します。

「シェルの実行」に書いてあった、「Sphinxをビルドするコマンド」を”post build task”側のスクリプト域にコピーして下さい。

コピー元となった「シェルの実行」は、削除しておいてください。

また、前述で作成した「成果物を保存」の箇所から「高度な設定…」をクリックして下さい。

表示されたチェックボックス中”成果物が何もない場合でもビルドを失敗にしない”をチェックし、ジョブを保存して下さい。

これにて、Sphinxのビルドはプログラムのビルドと別の扱いに成ります。

以上、いかがでしたでしょうか。 間違いや「もっとこういうのあるよ！」がありましたら、お教え下さい。

検証環境

• CentOS6.5 + Jenkins ver.1.575 (java -jer にて実行)
• cloudbees.com の Jenkins ver. 1.554.2.3