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

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

saronpasuの中身(ruby
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 が展開されます。

6. 改めて、HTML Help ドキュメントを生成してみよう


これで準備は整いました。
改めて、RDocの生成コマンドを実行しましょう。

$ rdoc -c utf-8 -m Main -t SampleProject -f chm lib main.rb



これでようやく、 sample_project/doc/rdoc.chm が生成されました。
これを開くと、 HTML Helpとしてドキュメントを見る事ができますね。

 

生成されたHTML Helpドキュメント

インターネット経由で APIリファレンスを見るのも良いですが、どうしてもインターネットに接続できない場合や
自分で書いたRubyプログラムにドキュメントを付けたい場合なんかにはRDocは重宝します。



普段から RDocを生成することを意識してコメントを書いていると、自然と綺麗なコメントが書けるようになるかもしれませんね。

コメント (0)  |トラックバック (0)

ブックマークに追加する Subscribe with livedoor Reader あとで読む

トラックバック URL

この記事にコメントする

ニックネーム:
メールアドレス:
URL:


KBMJのWebソリューション
Ruby on Rails Summer Festival 2008開催決定!!

TOPICS

2008/06/25
ZD Net Builder」の連載記事です。第四回は「Rubyでどう書く?:重複したRSSをまとめる」が掲載されました。

2008/05/30
ZD Net Builder」の連載記事です。第三回は「Rubyでどう書く?:Rubyで特定URLの画像パス一覧を表示する」が掲載されました。

2008/05/07
ZD Net Builder」に連載を始めました。第二回は「Rubyでどう書く?:RubyでPDF履歴書を作成する」が掲載されました。

2008/04/24
アットマーク・アイティ」に『 Rubyを使ってPaSoRi経由でSuicaの乗車履歴を取得し、GoogleMapsやGoogleEarthで表示する』が掲載されました。

全体のRoR最新ブログ一覧

プロフィール

  • saronpasu
  • RubyやRuby on Railsで開発して行く上でのTipsや、トラブルにぶつかった際の解決方法なんかを公開して行きます。

ブログの購読

RSS

timelog
株式会社ケイビーエムジェイロゴ