読者です 読者をやめる 読者になる 読者になる

しおしお

IntelliJのあれやこれや

GradleでSphinxをビルドしてみた。

Gradle Sphinx Groovy

お仕事でSphinxでドキュメント書いてて、Gradleでビルドしてるときたら、SphinxもGradleからビルドしないとダメだよねってことでやってみた。

お試しプロジェクトの構成はこんな感じで、プロジェクト直下のdocディレクトリにドキュメントが格納されていると。
f:id:sioiri:20120603212202p:plain

まずは、Execタスクを使ってビルドをしてみたけど、なんか普通すぎてつまらない。
Execタスクのドキュメント→Exec - Gradle DSL Version 1.0-rc-3

task buildDoc(type : Exec) {
  workingDir 'doc'
  commandLine 'make', 'html'
}

あまりにもつまらなすぎたので、Sphinx用のタスクを作ったりしてみました。
Sphinxタスクの使い方やソースはこちら→siosio/Sphinx-GradlePlugin · GitHub

Sphinxタスクの使い方

Sphinxタスクのソースを「プロジェクトルーツ/buildSrc/src/main/groovy」に配置する。下の画像のように。
f:id:sioiri:20120603214419p:plain

build.gradleにタスクを追加する。追加したタスクの引数には、「type: Sphinx」指定してあげます。
ボディ部では、Sphinxのプロパティに必要な値を設定する必要があるんだけど、デフォルト値のままの場合は特に必要無いです。。
例えば、ドキュメントのルートディレクトリのデフォルト値は「document」だけど、今回のプロジェクトでは「doc」だよって場合には、下のようにdocumentRootにdocを設定してあげれば良い。

task buildDoc(type : Sphinx) {
  documentRoot "doc"
}

ビルドを実行すると・・・ちゃんとドキュメントビルドされてる!!

shioiri-no-MacBook-Air:gradle-test siosio$ gradle buildDoc
:buildSrc:clean UP-TO-DATE
:buildSrc:compileJava UP-TO-DATE
:buildSrc:compileGroovy
:buildSrc:processResources UP-TO-DATE
:buildSrc:classes
:buildSrc:jar
:buildSrc:assemble
:buildSrc:compileTestJava UP-TO-DATE
:buildSrc:compileTestGroovy UP-TO-DATE
:buildSrc:processTestResources UP-TO-DATE
:buildSrc:testClasses UP-TO-DATE
:buildSrc:test
:buildSrc:check
:buildSrc:build
:buildDoc
sphinx-build command line option:-b html doc build/document
Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index

writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

BUILD SUCCESSFUL

Jenkinsでも実行してみよう

JenkinsのGradleビルドで「buildDoc」タスクを実行できるように変更
Javaのbuildと一緒にやるので、「build buildDoc」とTasksに設定してます。
f:id:sioiri:20120603220531p:plain

ビルドを実行すると、ワークスペースの「build/document」配下にビルド結果のドキュメントが出力されます。
f:id:sioiri:20120603220642p:plain

開いてみると、ちゃんとビルドされてるね。あとは、良さ気に公開するとビルドしたドキュメントをプロジェクトメンバーが見れるようになるわけだね。
f:id:sioiri:20120603220657p:plain

おわり。