目次
この記事はアピリッツの技術ブログ「DoRuby」から移行した記事です。情報が古い可能性がありますのでご注意ください。
こんにちは！
井上 清晃(saronpasu)です。
今回は、RDocについてご紹介します。
RDocについて簡単に説明すると、『Rubyのソースコードから説明書を生成してくれる』というものです。
1. RDocにできること
RDocは、Rubyのソースコードに書いてあるコメントやクラス定義から、
ドキュメントを生成してくれる便利なツールです。
RDocでは次の出力フォーマットに対応しています。
・HTML ドキュメント
Railsなどを触っている方は、もう既にご覧になっているのではないでしょうか？
おなじみの、フレームで区切られたAPIリファレンスのページがあります。
あれがまさに、ソースコードを元に、RDocで生成されたものです。
・HTML Help ドキュメント
Windowsユーザのみなさんは見慣れている、Helpファイルです。
Rubyのソースコードを元に、HTML Help形式のドキュメントを生成することができます。
他にも、
・XML ドキュメント や
・クラス図(jpg/gif/png) などの出力もサポートしていますが、これらについては、今回は割愛します。
2. SampleProject を用意してみよう
さて、それではまず 任意のプロジェクトとして、 SampleProjectというもののドキュメントを生成してみましょうか。
SampleProjectのファイル構成
sample_project/
Rakefile
README
test/*.rb
lib/*.rb
main.rb
ざっと、こんな構成になっていると仮定しましょう。
このスクリプトは、 main.rb に記述されている Mainというクラスを基本的に扱うものとします。
そして、main.rb は、lib/以下の.rbファイルをrequire()して動作しているものとしましょう。
#!/usr/bin/ruby -Ku
require ‘lib/hoge.rb’
require ‘lib/fuga.rb’
#
#*MainClass
# UTF-8で MainClass の使い方を書いています。
#
class Main
def initialize
#ここに処理をかくよ
end
end
3. RDocで HTMLドキュメントを生成してみよう
さて、早速 RDocでソースコードから HTMLドキュメントを生成してみましょう。
$ rdoc -c utf-8 -m Main -t SampleProject -f html lib main.rb
コマンドの内容を説明します。
-c: 文字コードの設定です。今回は UTF-8で記述しているのでそのように指定しました
-m: 生成するドキュメントのトップページに表示するクラス(またはモジュール)です。今回は Mainクラスを指定しました。
-t: 生成するドキュメントのタイトルです。今回は SampleProject と指定しました
-f: 生成するドキュメントの形式を指定します。今回は HTML で出力するように指定しました
最後に、引数としてソースコードの場所を指定します。testとかは読ませたくないので、今回は libディレクトリと main.rbを指定しました。
こうすると、sample_project/配下に docというディレクトリが生成されて、そこに index.htmlという HTMLドキュメントが生成されます。
4. RDocで HTML Help ドキュメントを生成してみよう
それでは、次に HTML Help ドキュメントを生成してみましょう。
先ほどの SampleProject から、HTML Helpを生成します。
$ rdoc -c utf-8 -m Main -t SampleProject -f chm lib main.rb
そうすると・・・
Generating CHM…
.chm output generation requires that Microsoft’s Html Help
Workshop is installed. RDoc looks for it in:
c:/Program Files/HTML Help Workshop/hhc.exe
You can download a copy for free from:
というようなメッセージが表示されました。
5. HTML Helpの生成に必要な、 『HTML Help Workshop』をインストールしよう
騙していたわけではありませんが、実は HTML Helpを生成するためには Microsoft HTML Help WorkShop が必要なのです。
というわけで、 Microsoft HTML Help WorkShopをインストールしましょう。
2008.04.30 現在、「HTML Help WorkShop」 は、「Office 2003 Edition リソースキット」として配布されています。
次の URLから 「Office 2003 Edition リソースキット」を取得しましょう。
http://www.microsoft.com/japan/office/ork/2003/tools/BoxA02.htm
ork.exeをインストールすると、 C:\Program Files\ORKTOOLS\ORK11\TOOLS\HTML Help Workshop に、HTMLHELP.EXEが展開されています。
今度は、この HTMLHELP.EXE を展開すると、 C:\Program Files\HTML Help Workshop\hhc.exe が展開されます。
6. 改めて、HTML Help ドキュメントを生成してみよう
これで準備は整いました。
改めて、RDocの生成コマンドを実行しましょう。
$ rdoc -c utf-8 -m Main -t SampleProject -f chm lib main.rb
これでようやく、 sample_project/doc/rdoc.chm が生成されました。
これを開くと、 HTML Helpとしてドキュメントを見る事ができますね。
インターネット経由で APIリファレンスを見るのも良いですが、どうしてもインターネットに接続できない場合や
自分で書いたRubyプログラムにドキュメントを付けたい場合なんかにはRDocは重宝します。
普段から RDocを生成することを意識してコメントを書いていると、自然と綺麗なコメントが書けるようになるかもしれませんね。
