Ruby Documentation System (RDoc) とは, Ruby で書かれたソースコードから ドキュメントを自動生成する, Ruby 本体に付属する標準ライブラリの1つです.
RDoc は Ruby ソースコードを解析し, クラス, モジュール, メソッドの定義 を抜き出し, include や require に関して解釈します. そしてこれらの内容 とその直前に書かれたコメントを併合し, HTML ドキュメントを出力しま す. 詳しくは参考資料 1,2 を参照ください.
以下では, まず RDoc のインストールを行います. そして Ruby で簡単なクラ スライブラリを作成し, RDoc を用いてそのプログラムからドキュメントを生 成してみます.
前提として, Ruby 本体のインストールは行っておいてください.
Fedora Core の場合
# yum install rdoc
Vine, Debian の場合
# apt-get install rdoc
空のディレクトリを作成し, そのディレクトリ内に移動してください. その ディレクトリ内で, rdoc というコマンドが実行できることを確認して ください.
$ mkdir rdoc_test $ cd rdoc_test $ rdoc
以下のようなメッセージが表示され, doc というディレクトリが作成 されていれば OK です.
Generating HTML... Files: 0 Classes: 0 Modules: 0 Methods: 0 Elapsed: 0.262s
まず, GPhys を用いて簡単なクラスライブラリを作成しましょう. (これより も前のチュートリアルで既に GPhys は利用可能な状態だと仮定しています). 以下のプログラムを作成してください. <URL:sample/gphys_cont1.rb>
class GPhys_cont
require "numru/ggraph" ; include NumRu
FILENAME = 'T.jan.nc'
attr_reader :var
def initialize(var='T')
@var = var
end
def cont
gphys = GPhys::IO.open(FILENAME, @var)
DCL.gropn(1) ; DCL.sgpset('lcntl', false) ; DCL.uzfact(0.7)
GGraph.contour( gphys)
DCL.grcls
end
end
if __FILE__ == $0
gphys = GPhys_cont.new
gphys.cont
end
if __FILE__ == $0 以降の部分は, このプログラムを実行した際の
メイン文に当たります. このプログラムは実際には
GPhys チュートリアル -- 6. とりあえず可視化
のように動作します. 以下のデータファイルをダウンロードした後, 上記の
Ruby スクリプトを ruby で実行してみてください.
$ ruby gphys_cont1.rb
もう1つ, このクラスを継承したクラスライブラリを作成してみましょう. 以下のプログラムを作成してください. <URL:sample/gphys_tone1.rb>
require "gphys_cont1"
class GPhys_tone < GPhys_cont
attr_accessor :draw_tone
def initialize
super
@draw_tone = true
end
def tone(itr=1)
gphys = GPhys::IO.open(FILENAME, @var)
DCL.gropn(1) ; DCL.sgpset('lcntl', false) ; DCL.uzfact(0.7)
GGraph.set_fig( 'itr'=>(itr == nil) ? 1 : itr.to_i)
GGraph.tone( gphys ) if @draw_tone
GGraph.contour( gphys, !@draw_tone )
DCL.grcls
return true
end
end
if __FILE__ == $0
gphys = GPhys_tone.new
gphys.tone
end
このプログラムは, gphys_cont1.rb の色塗り版です.
$ ruby gphys_tone1.rb
では次に, RDoc を用いてこのクラスライブラリのリファレンスマニュアルを 自動生成してみましょう. gphys_cont1.rb, gphys_tone1.rb が置いてあるディ レクトリで以下のコマンドを実行してください.
$ rdoc gphys_cont1.rb gphys_tone1.rb --main GPhys_cont
このコマンドにより, doc というディレクトリが作成され, その中に RDoc に よって作成されたドキュメントが出力されたはずです. ブラウザで doc/index.html を見てみましょう. 以下のようなページが表示されるはずです.
上段の 3 分割されたフレームにファイル, クラスおよびモジュール, メソッ ドのリストが表示されています. 下の部分には GPhys_cont クラスの内容が 表示されています. 下のフレームのメソッド名の部分をクリックすると, ソー スコードが表示されます.
ソースコードにコメントを埋め込むことで, ドキュメントにより多くの 情報を付加してみましょう. gphys_cont1.rb にコメントを追加した 以下のファイルを作成しましょう.
#
# GPhys を利用して等値線図を描画するクラスライブラリ
#
class GPhys_cont
require "numru/ggraph" ; include NumRu
# ファイル名 (固定)
FILENAME = 'T.jan.nc'
# 描画する変数
attr_reader :var
#
# 初期化処理用のメソッド. 引数 _var_ には描画する変数を
# 与えます.
#
def initialize(var='T')
@var = var
end
#
# ※ 空行を入れると, それより上の部分は無視されます.
#
#
# 等値線図の描画を実行します.
#
def cont
gphys = GPhys::IO.open(FILENAME, @var)
DCL.gropn(1) ; DCL.sgpset('lcntl', false) ; DCL.uzfact(0.7)
GGraph.contour( gphys)
DCL.grcls
end
end
if __FILE__ == $0
gphys = GPhys_cont.new
gphys.cont
end
クラスやメソッド定義の直前に書かれているコメントが各々のドキュメントと して解釈されます. なお, 空行をいれた段階でそれよりも上部の部分 (上のソー スコードで言うと「※ 空行を入れると...」の部分) はドキュメントとして解釈 されません.
では, 再度 rdoc コマンドを実行してみましょう.
$ rdoc gphys_cont2.rb gphys_tone1.rb --main GPhys_cont --charset euc-jp
今度は, 以下のようなページが生成されます.
ソースコード内のクラスやメソッドの上部に書かれたコメントがドキュメントに 反映されているのが分かります.
RDoc のコメント部はかなり自然に書くことができますが, いろいろな修飾も可能になっています.
gphys_tone1.rb にコメントを追加した以下のファイルを作成しましょう.
require "gphys_cont2"
#
#= GPhys を利用して色塗り図を描画するクラスライブラリ
#
#Authors:: 森川 靖大
#Version:: 1.2 2006-03-08 morikawa
#Copyright:: Copyright (C) GFD Dennou Club, 2006. All rights reserved.
#License:: Ruby ライセンスに準拠
#
#-- (#-- から #++ までの部分を RDoc は解釈しません.)
#"=", "==", ""===" は見出しを表します.
#
#= 見出しレベル1
#== 見出しレベル2
#=== 見出しレベル3
#++
#
#このクラスのスーパークラスは GPhys_cont です.
#new メソッドで初期化を行い, tone メソッドで描画を行います.
#
#--
# モジュール名やメソッド名はそのままモジュールやメソッドへのリンクに
# 変換されます.
#++
#
#=== 参考資料
#
#* http://ruby.gfd-dennou.org
# 1. GPhys[http://www.gfd-dennou.org/library/ruby/products/gphys/]
# 2. {2006 年 電脳rubyセミナー・電脳davis/rubyワークショップ}[http://www.gfd-dennou.org/library/ruby/workshop200603/]
#
#--
#==リストの表示に関して
#
#リストは以下のような記号が付いたパラグラフです.
#
# - '*' もしくは '-' で普通のリスト
# - 数字+ピリオドで番号付きリスト
# - アルファベット+ピリオドでアルファベットリスト
#
#
#== リンクに関して
#
# http:, mailto:, ftp:, www. で始まるテキストはウェブへのリンクだと
# 判別されます.
#
# label[url] の形式でもハイパーリンクが張れます. この場合は lavel が表
# 示され, url がリンク先となります. label が複数の単語を含んでいる場合
# (日本語の場合はこっちを使ってください), 中括弧を使い, <em>{multi word
# label}[</em>url<em>]</em>としてください.
#++
#
#=== 開発履歴
#
#* 1.2 2006-03-08
# * 堀之内さんのコメントを下に, 作者やライセンス, 開発履歴の
# 欄を足してみる.
#
#* 1.1 2006-03-07
# * とりあえず作成してみる.
#
class GPhys_tone < GPhys_cont
# 図に色塗りを行うかどうかのフラグ.
# このフラグを false や nil にした場合, GPhys_cont#cont と
# 同様に動作します.
#
attr_accessor :draw_tone
#
#=== 初期化処理用メソッド
#
#GPhys_cont#new を参照してください.
#
#--
# 別のモジュール内のメソッドへリンクする場合は
# "<i>モジュール名</i>#<i>メソッド名</i>" と指定します
#++
#
def initialize
super
@draw_tone = true
end
#=== 描画メソッド
#
#色塗り図を描画するメソッド. 等値線図のみを描画したい場合は
#GPhys_cont#cont を利用してください.
#
#_itr_ :: 描画する際の地図投影法を指定します. 数値を与えてください.
# デフォルトは 1 になっています. 番号と投影法の関係に関しては
# http://www.gfd-dennou.org/library/dcl/dcl-f90/doc/term/2d.htm
# を参照ください
#
#返り値:: 常に true が返ります.
#
def tone(itr=1)
gphys = GPhys::IO.open(FILENAME, @var)
DCL.gropn(1) ; DCL.sgpset('lcntl', false) ; DCL.uzfact(0.7)
GGraph.set_fig( 'itr'=>(itr == nil) ? 1 : itr.to_i)
GGraph.tone( gphys ) if @draw_tone
GGraph.contour( gphys, !@draw_tone )
DCL.grcls
return true
end
end
if __FILE__ == $0
gphys = GPhys_tone.new
gphys.tone
end
では, 再度 rdoc コマンドを実行してみましょう.
$ rdoc gphys_cont2.rb gphys_tone2.rb --main GPhys_tone --charset euc-jp
今度は, 以下のようなページが生成されます.
モジュールやメソッドなどに自動的にリンクがはられ, 見出し, リスト表示 が行われていることがわかります.
修飾のための書式に関して, ソースコードに解説が付記してあるので参照して
ください. より詳しい情報は, 参考資料 1, 2 の "MarkUp" の部分を参
照してください. ソースコード内で解説が書き込んである '#--' 〜
'#++' の部分に関しては RDoc は無視するため, ドキュメントに反映さ
れません.
rdoc コマンドのオプションのうち, 上記で説明しなかった便利なものをいく つか紹介します. より詳しい情報は, 参考資料 1, 2 の "Usage" また は "使い方" の部分を参照してください.
以下のコマンドで作成したドキュメントを載せておきます. (コマンドプロンプトや DOS 窓を利用している方がコピペしやすいように, 改行しないものも載せておきます)
$ rdoc gphys_cont2.rb gphys_tone2.rb --main GPhys_tone \
--charset euc-jp --inline-source --diagram \
--title "GPhys_tone and GPhys_cont Documentation"
$ rdoc gphys_cont2.rb gphys_tone2.rb --main GPhys_tone --charset euc-jp --inline-source --diagram --title "GPhys_tone and GPhys_cont Documentation"
RDoc を用いて作成されたドキュメントをいくつか紹介します.