スマートな検索ができるRDocを自分のプロジェクトでも使う方法

haga — Thu, 02 Apr 2009 17:22:16 +0000

はじめに

先日エントリーに書いた「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

参考ページ

さいごに

当初はsdocを使いたいというよりも、RDocのテンプレートの書き方を知りたいと思っていろいろ探したんですが、いまいち良くわからなかった。テンプレートとフォーマットの違いって何だろう？

調べながらRDocのソースを読んでいると、やっぱすごい人のソースはすごいなぁと。こういうメジャーなライブラリのひとつやふたつ隅から隅まで読んでみる、なんてことしてみたいが・・。

func09 » rdoc