便利かどうかわからないが Grails1.2M2のドキュメント生成を試してみた

...いや，これから便利になるんだろう。

Grails1.2M2からGrails User Guideと同じドキュメントエンジンがユーザプロジェクトでも使えるようになるというので試してみた。まだ正式版じゃないので，微妙なところもあるけれど，これはちょっと面白い。

1.2M2のリリースノートには，

Project Documentation Engine
The same documentation engine that powers the Grails reference documentation is now available in your projects. Simply create your documentation inside the src/docs/ref and src/docs/guide directories of your project. See the Grails documentation source for an example.
Grails - The search is over.

てな具合で，サンプル読めとだけ書いてあったが，1.2M2のユーザガイドを眺めてみたら，ちゃんとこのこと書いてあった。
→ Grails 1.2M2 - 3.6 Project Documentation

大体の事はユーザガイドにゆずるとして，実際試してみてビミョーと思った事を残しておく。

ファイル名がそのまま章のタイトルになる
"1 Introduction.gdoc"とか"2.1 Downloading and Installing.gdoc"というファイル名が，まんまドキュメントの章タイトルになる。むろん，日本語のタイトル付けたければ，そうゆうファイル名にする。
OSXとWindowsXPで試してみたけど，お互いファイル名がユニコード(UTF-8?)なんで，文字化けするってことは無かった。なんつーか１バイト圏らしい割り切りだなーって思う。

Windows系だとちょっと注意が必要
gdocファイルの中身はデフォルトエンコードで読み込まれるので，cp932で書いとくといい（OSXの場合はutf-8でおk）。ドキュメントエンジンもデフォルトエンコードのまま処理するんだけど，HTMLのテンプレのタグには"charset=utf-8"って書いてあるので，賢いブラウザで見るともれなく文字化けする。
しかたないんで，$GRAILS_HOME/scripts/_GrailsDocs.groovyを直接編集して，withWriter使っているところを次のように直すといい（手当たり次第でいいと思う）。

new File("${refPagesDir}/${title}.html").withWriter {
         ↓
new File("${refPagesDir}/${title}.html").withWriter("utf-8") {

イメージファイルの置き場所がありそでない
!imagefile.png!って記述でイメージファイルを参照できるっぽいんだけど，ローカルのイメージファイルをどこに置いたらいいかがわかんなかった（生成した後は $APP_HOME/docs/manual/imgなんだけど，その元の置き場所のことね）。
というか，ソース（_GrailsDocs.groovy）見たらイメージファイルを回収するコードがなかったから，まだそうゆう事できないんだって理解した（それでも俺様パッチあてれば済む話）。

リファレンスのひな形を生成できるっぽい
ドキュメントの左側のフレームに表示されてあるアレ。これもソースみると，ひな形つくる機能がありそうなんだけど，まだそこまで実装しきれてないみたい。
あとこれ，作ったら作ったで便利なのかも知れんが，groovydocとどう住み分けしたらいいんだろか？
＃そのうち，このページからjavadoc, groovydocへのリンクがつくようになるんかな？

ついでに，表紙の関連情報は application.properties と Config.groovyから引用されるみたい。せっかくだからConfig.groovyの内容も載っけておく。

grails.doc.copyright="COPYRIGHTはここに展開される。"
grails.doc.license="ライセンスはどこに展開される？"
grails.doc.authors="作者はここに展開される。"
grails.doc.footer="フッターはここ。<a href='http://grails.org'>grails</a>"

ドキュメント生成コマンドは"grails docs"じゃなくて"grails doc"が正解
マニュアルか実装のどっちかがtypoしてんだけど，1.2M2では "grails doc" が正解。

以上，ちょっとケチつけちゃうところもあるけど，APIリファレンス以外のドキュメント生成機能が標準に盛り込まれるのはとても良いと思う。Grailsから切り出してくれたって良いくらいで，むしろこうゆうのJavaにも欲しい。

エコシステムって言うの？Grailsもいろいろ周辺機能が揃って来て，Grailsだけで結構いろんなことできるようになってきたって感じ。あとはテストまわりで革命的な事が起きてくれると，とってもうれしいんだけどな。:-D