ホーム DoRuby Rubyのソースコードから HTML Helpを生成してみよう!

Rubyのソースコードから HTML Helpを生成してみよう!

この記事はアピリッツの技術ブログ「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:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

というようなメッセージが表示されました。

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を生成することを意識してコメントを書いていると、自然と綺麗なコメントが書けるようになるかもしれませんね。

記事を共有
モバイルバージョンを終了