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

ランプの中身(Ruby on Railsのシステム開発): ランプの中身(Ruby on Railsのシステム開発)では、株式会社ケイビーエムジェイのRuby on Railsエンジニアが蓄積したノウハウを公開しています。Ruby on Railに関する技術解説や実践的なノウハウなど、開発現場の技術に則したコンテンツを随時追加していきます。初心者の方でもわかりやすい技術解説を心がけています。リクエスト、ご質問も受け付けいますので、ご気軽にコメントを記述して下さい。

< Rubyのコマンドライン引数と環境変数に... | メイン | Rubyプログラムの組み方から、Exeフ... >

: 2008.04.30; Rubyのソースコードから HTML Helpを生成してみよう！

こんにちは！
井上清晃(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ドキュメントが生成されます。

生成された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 が展開されます。