はじめに
先日エントリーに書いた「Rails Searchable API Doc」のような、便利なRDocを自分のプロジェクトにも適用したい。 それを可能にするためのGemパッケージ「sdoc」がRails Searchable API Docの作者から提供されています。
これはさっそく使ってみたいと思います。
インストール
githubからインストールします。
jsonとrdocの新しいバージョンを要求されますのでインストールしておきます。
- sudo gem install rdoc
- sudo gem install json
- sudo gem install voloko-sdoc --source http://gems.github.com
これでsdocというコマンドが実行できるようになりました。
sdocはrdocにSHTMLというフォーマットを追加してラップしただけのもののようです。
ちなみにRDocの2.4からだと思うのですがデフォルトのテンプレートがDarkFishというちょっとクールなものに変わっているみたいです。あんまりRubyっぽくないデザインです。
使い方
使い方は非常に簡単です
- sdoc ディレクトリ名
と実行すればdocフォルダを作成しその中にドキュメントのHTMLを作成してくれます。
Railsのプロジェクトをドキュメント化したい場合、プロジェクトフォルダ内で
- sdoc . -o doc/s_app -U -x vendor -x test -x doc -x tmp -x script -x public -x log -x config
と実行すればOKです。
無視するディレクトリは-xオプションで指定します。
Rake化
単純なRakeタスクにしておいても良いでしょう。
Railsのプロジェクトのlib/taskにsdoc.rakeというファイルを生成して、以下のようにシェルを実行する記述をします。
- # lib/task/sdoc.rake
- namespace :doc do
- namespace :sdoc do
- desc "Generate SDoc Documentation"
- task :app do
- output = 'doc/s_app'
- ignores = %w{vendor test doc tmp script public log config}
- rm_rf output
- option_exclude = ignores.map{|i| "-x #{i}"}.join(" ")
- sh "sdoc . -o #{output} -U #{option_exclude}"
- end
- end
- end
で、Rakeタスクを実行です。
- rake doc:sdoc:app
で、ドキュメントをdoc/s_appに生成します。
どうですか？サーチャブルなRDocが自分のプロジェクトにも適用されました！
これはがんばってコメントを書こうというモチベーションにも繋がります！素晴らしい！
バグ
素晴らしいと喜んでいたのも束の間、バグを見つけました。（2009-04-03現在）
ドキュメントのテンプレートの中に「%charset%」という置き換えされない文字列がありました。
そうです文字コード指定ができないので、日本語が化け化けです。
大したバグじゃないのでGithubでフォークして直してみました。
本体にプッシュ要求する方法を知らないのでどうしたらいいのだろうか・・？英語も書けないしなー。だれかテーチミー。
直したdiff http://github.com/func09/sdoc/commit/820e29a25efc7957d25dda4d128cae9f2e20844d
参考ページ
- http://railsapi.com/
- http://github.com/voloko/sdoc/tree/master
- hannaテンプレートでgemのrdocをスタイリッシュに
- http://github.com/func09/sdoc/commit/820e29a25efc7957d25dda4d128cae9f2e20844d
さいごに
当初はsdocを使いたいというよりも、RDocのテンプレートの書き方を知りたいと思っていろいろ探したんですが、いまいち良くわからなかった。テンプレートとフォーマットの違いって何だろう？
調べながらRDocのソースを読んでいると、やっぱすごい人のソースはすごいなぁと。こういうメジャーなライブラリのひとつやふたつ隅から隅まで読んでみる、なんてことしてみたいが・・。
