Ruby Documentation System (RDoc) とは, Ruby で書かれたソースコードから ドキュメントを自動生成する, Ruby 本体に付属する標準ライブラリの1つです.
RDoc は Fortran 90/95 で書かれたソースコードからも ドキュメント生成を行うことができます. Fortran 90/95 の解析機能を強化した, RDoc Fortran 90/95 ソースコード解析機能強化版 を用いることで, 実用レベルのリファレンスマニュアルの生成が可能です.
以下では, まず RDoc Fortran 90/95 ソースコード解析機能強化版 のインストールを行います.
そして Fortran 90/95 で簡単なモジュールを作成し, RDoc を用いてそのプログラムからドキュメントを生成してみます.
前提として, Ruby 本体のインストールは行っておいてください.
ここでは, Ruby 本体は既にインストールされていると考え, RDoc Fortran 90/95 ソースコード解析機能強化版 から tar.gz パッケージを入手してインストールを行います. なお, Debian GNU/Linux をお使いの方は インストール (Debian GNU/Linux の場合) を参照ください.
上記サイトから「rdoc-f95 tar.gz パッケージ」をダウンロードし, 以下のように tar コマンドで展開後, 展開されたディレクトリに移動し, install.rb でインストールを行ってく ださい. なお, 既に rdoc がインストールされている場合, 上書きする可能性があります.
% tar -zxvf rdoc-f95.tgz % cd rdoc-f95-XXXXXXXX % ruby install.rb
インストール先のディレクトリや, 変更のためのオプションに関しては, 以下 のコマンドで知ることが出来ます.
% ruby install.rb --help
ただし, 明示的にインストール先のディレクトリを指定した場合には, 環境変数 PATH, RUBYLIB の設定も行ってください.
なお, RDoc Fortran 90/95 ソースコード解析機能強化版 では Ruby 本体のパッチも配布しています.
以下の URL を APT のソースリスト (/etc/apt/sources.list) に加えま す. プロトコルとして http の代わりに ftp を用いることも可能です.
deb http://www.gfd-dennou.org/library/cc-env/Linux/debian-dennou etch/
APT のコマンドでインストールを行ないます.
% apt-get update % apt-get install rdoc-f95
このパッケージはオリジナルの rdoc パッケージのファイル群を退避した場所 へ移動させるため, オリジナルの rdoc パッケージが使用できなくなりま す. オリジナルの rdoc パッケージを使用する場合は rdoc-f95 パッケージを 削除してください. 退避されたオリジナルの rdoc パッケージのファイル群が 本来の場所に復帰します.
空のディレクトリを作成し, そのディレクトリ内に移動してください. その ディレクトリ内で, rdoc というコマンドが実行できることを確認して ください.
% mkdir rdoc_test % cd rdoc_test % rdoc
以下のようなメッセージが表示され, doc というディレクトリが作成 されていれば OK です.
Generating HTML... Files: 0 Classes: 0 Modules: 0 Methods: 0 Elapsed: 0.262s
まず, サンプルとして Fortran 90/95 で 簡単なモジュールと主プログラムを作成します. もしも手元に Fortran 90/95 で書かれたプログラムがあるならば それを用いて試してみても良いでしょう. 以下では, 台形公式を用いた簡単な数値積分のプログラムを例として用います.
program calc
use integral, only: trapezoid
integer :: n, ios
real :: a, b
namelist /nml/ a, b, n
write(*,*) ' Input interval (a,b) and division number (n) like'
write(*,*) ' "&nml a=0, b=10, n=100 /"'
read(*, nml, iostat = ios)
if ( ios == 0 ) then
s = trapezoid(a,b,n)
write(*,*) s
else
write(*,*) ' Error: input data is invalid.' ; stop
end if
end program calcmodule integral
private
public trapezoid
contains
function trapezoid(a,b,n) result(s)
real, intent(in) :: a
real, intent(in) :: b
integer, intent(in), optional :: n
real :: s
real :: h
integer :: i, div = 10
if (present(n)) div = n
h = (b-a) / div
s = (f(a)+f(b)) / 2.0
do i = 1, n-1
s = s + f(a + i*h)
end do
s = h*s
end function trapezoid
function f(x) result(res)
real, intent(in) :: x
real :: res
res = x**2 - 2*x + 2
end function f
end module integralもしも Fortran 90/95 コンパイラが手元の環境にあるのであれば, 以下のようにコンパイルと実行ができます. 積分区間と領域分割数を 与えることで数値積分の結果が得られます. (なお, 今回のチュートリアルではプログラムのコンパイルや実行は 必要ではありません).
% f90 calc01.f90 integral01.f90 -o calc01 % ./calc01
では次に, RDoc を用いてこのモジュールと主プログラムのリファレンスマニュアルを 自動生成してみましょう. calc01.f90 と integral01.f90 が置いてあるディ レクトリで以下のコマンドを実行してください.
% rdoc calc01.f90 integral01.f90 --main integral --ignore-case -U
このコマンドにより, doc というディレクトリが作成され, その中に RDoc に よって作成されたドキュメントが出力されたはずです. ブラウザで doc/index.html を見てみましょう. 以下のようなページが表示されるはずです.
上段の 3 分割されたフレームにファイル, モジュール, サブルーチンや 関数や変数や定数などのリストが表示されています. 下の部分には integral モジュール の内容が 表示されています. 下のフレームのサブルーチンや関数の名称をクリックすると, ソースコードが表示されます.
ソースコードにコメントを埋め込むことで, ドキュメントにより多くの 情報を付加してみましょう. calc01.f90, integral01.f90 にコメントを追加した 以下のファイルを作成しましょう.
program calc
!
! integral モジュールにより台形公式を用いた数値積分を行う
! 主プログラムです.
!
use integral, only: trapezoid
integer :: ios
real :: a ! 積分区間の下限
real :: b ! 積分区間の上限
integer :: n ! 積分区間の分割数
namelist /nml/ a, b, n
!
! 積分区間に関して入力を行うための NAMELIST 変数群名です.
!
write(*,*) ' Input interval (a,b) and division number (n) like'
write(*,*) ' "&nml a=0, b=10, n=100 /"'
read(*, nml, iostat = ios)
if ( ios == 0 ) then
s = trapezoid(a,b,n)
write(*,*) s
else
write(*,*) ' Error: input data is invalid.' ; stop
end if
end program calcmodule integral
!
! 台形公式を用いた数値積分を行うための手続きを提供する
! モジュールです.
!
private
public trapezoid
contains
function trapezoid(a,b,n) result(s)
!
! 台形公式を用いた数値積分を行います.
!
! $ f(x) = x^2 - 2x + 2 $ の積分値を台形公式によって求めます.
!
! * 積分区間は $ [a, b] $ とします.
! * 実際に計算する式は以下の通りです.
! ここで $ h $ は $ h = \frac{b-a}{n} $ です.
!
! \[
! \int_{a}^{b} f(x) dx =
! \frac{h}{2} \left\{f(a) + f(b)\right\} + h\sum_{i=1}^{n-1} f(a+ih)
! \]
!
! このサンプルプログラムは http://www.gfd-dennou.org/library/dcmodel
! にて入手できます.
!
!
! ※ 空行を入れると, それより上の部分は無視されます.
!
real, intent(in) :: a ! 積分区間の下限
real, intent(in) :: b ! 積分区間の上限
integer, intent(in), optional :: n ! 積分区間の分割数
real :: s ! 積分値
real :: h
integer :: i, div = 10
if (present(n)) div = n
h = (b-a) / div
s = (f(a)+f(b)) / 2.0
do i = 1, n-1
s = s + f(a + i*h)
end do
s = h*s
end function trapezoid
function f(x) result(res)
!
! $ f(x) = x^2 - 2x + 2 $ の値を返す内部サブルーチンです.
!
real, intent(in) :: x
real :: res
res = x**2 - 2*x + 2
end function f
end module integralモジュール, サブルーチン, 関数, 変数, 定数の宣言文の行末もしくは 直後の行に書かれているコメントが 各々のドキュメントとして解釈されます. なお, 空行をいれた段階でそれよりも上部の部分 (上のソー スコードで言うと「※ 空行を入れると...」の部分) はドキュメントとして解釈 されません.
NAMELIST に関しても同様に, 付記されたコメントをドキュメントとして解釈します.
では, 再度 rdoc コマンドを実行してみましょう.
% rdoc -U calc02.f90 integral02.f90 --main integral --charset euc-jp --ignore-case
今度は, 以下のようなページが生成されます.
ソースコード内のモジュールやサブルーチンの行末もしくは直後の行に 書かれたコメントがドキュメントに反映されていることが分かります.
RDoc のコメント部はかなり自然に書くことができますが, いろいろな修飾も可能になっています.
integral02.f90 にコメントを追加した以下のファイルを作成しましょう.
module integral
!
!== 台形公式を用いた数値積分モジュール
!
! Authors:: 森川 靖大
! Version:: 0.3 2008-03-09 morikawa
! Copyright:: Copyright (C) GFD Dennou Club, 2006. All rights reserved.
!
!-- (#-- から #++ までの部分を RDoc は解釈しません.)
! "=", "==", ""===" は見出しを表します.
!
!= 見出しレベル1
!== 見出しレベル2
!=== 見出しレベル3
!++
!
! trapezoid サブルーチンに積分区間に関する情報を与えると,
! 計算を行い値を返します.
!
!--
! モジュール名やメソッド名はそのままモジュールやメソッドへのリンクに
! 変換されます.
!++
!
!=== 参考資料
!
! * http://www.gfd-dennou.org/library/dcmodel
! 1. {RDoc Fortran 90/95 ソースコード解析機能強化版}[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95]
! 2. {地球流体電脳davis/rubyワークショップ}[http://www.gfd-dennou.org/library/davis/workshop/2008-03-10/]
!
!--
!== リストの表示に関して
!
! リストは以下のような記号が付いたパラグラフです.
!
! - '*' もしくは '-' で普通のリスト
! - 数字+ピリオドで番号付きリスト
! - アルファベット+ピリオドでアルファベットリスト
!
!== リンクに関して
!
! http:, mailto:, ftp:, www. で始まるテキストはウェブへのリンクだと
! 判別されます.
!
! label[url] の形式でもハイパーリンクが張れます. この場合は lavel が表
! 示され, url がリンク先となります. label が複数の単語を含んでいる場合
! (日本語の場合はこっちを使ってください), 中括弧を使い, <em>{multi word
! label}[</em>url<em>]</em>としてください.
!++
!
!=== 開発履歴
!
! * 0.3 Ruby 用 RDoc チュートリアルを元に作ってみた.
!
private
public trapezoid
contains
function trapezoid(a,b,n) result(s)
!
! 台形公式を用いた数値積分を行います.
!
! $ f(x) = x^2 - 2x + 2 $ の積分値を台形公式によって求めます.
!
! * 積分区間は $ [a, b] $ とします.
! * 実際に計算する式は以下の通りです.
! ここで $ h $ は $ h = \frac{b-a}{n} $ です.
!
! \[
! \int_{a}^{b} f(x) dx =
! \frac{h}{2} \left\{f(a) + f(b)\right\} + h\sum_{i=1}^{n-1} f(a+ih)
! \]
!
! このサンプルプログラムは http://www.gfd-dennou.org/library/dcmodel
! にて入手できます.
!
!--
! 別のモジュール内のサブルーチンなどへリンクする場合は
! "<i>モジュール名</i>#<i>サブルーチン名</i>" と指定します.
!++
real, intent(in) :: a ! 積分区間の下限
real, intent(in) :: b ! 積分区間の上限
integer, intent(in), optional :: n ! 積分区間の分割数
real :: s ! 積分値
real :: h
integer :: i, div = 10
if (present(n)) div = n
h = (b-a) / div
s = (f(a)+f(b)) / 2.0
do i = 1, n-1
s = s + f(a + i*h)
end do
s = h*s
end function trapezoid
function f(x) result(res)
!
! $ f(x) = x^2 - 2x + 2 $ の値を返す内部サブルーチンです.
!
real, intent(in) :: x
real :: res
res = x**2 - 2*x + 2
end function f
end module integralでは, 再度 rdoc コマンドを実行してみましょう.
% rdoc -U calc02.f90 integral03.f90 --main integral --charset euc-jp --ignore-case
今度は, 以下のようなページが生成されます.
モジュールやサブルーチンなどに自動的にリンクがはられ, 見出し, リスト表示 が行われていることがわかります.
修飾のための書式に関しては,
RDoc Fortran 90/95 ソースコード解析機能強化版
の「書法」を参照してください.
ソースコード内で解説が書き込んである '#--' 〜
'#++' の部分に関しては RDoc は無視するため, ドキュメントに反映さ
れません.
rdoc コマンドのオプションのうち, 上記で説明しなかった便利なものをいく つか紹介します. より詳しい情報は, 参考資料 2, 3 の "Usage" また は "使い方" の部分を参照してください.
以下のコマンドで作成したドキュメントを載せておきます. (コマンドプロンプトや DOS 窓を利用している方がコピペしやすいように, 改行しないものも載せておきます)
% rdoc -U integral03.f90 calc02.f90 --main integral \
--charset euc-jp --inline-source --ignore-case \
--title "integral Documents"
% rdoc -U calc02.f90 integral03.f90 --main integral --charset euc-jp --inline-source --ignore-case --title "integral Documents"
TeX 記法で記したコメントを MathML 形式に変換して, 以下のような ドキュメントを作成してみます. (表示されている数式は画像張り込み ではありません).
MathML とは XMLベースの数式記述言語です. 詳細については 参考資料 4, 5, 6, 7 を参照してください.
MathML を含むドキュメントはブラウザによっては正しく表示されないことも あります. Mozilla Firefox および Internet Explorer (+ MathPlayer) では正しく表示されることを確認しています. その他のブラウザの MathML 対応に関しては, 参考資料 4, 5, 6, 7 を参照ください.
Ruby 用 MathML ライブラリのインストールを行います. なお, Debian GNU/Linux をお使いの方は Ruby 用 MathML ライブラリのインストール (Debian GNU/Linux の場合) を参照ください.
Ruby用MathMLライブラリ から math_ml-X.X.X.tar.gz ファイルをダウンロードします. (2008/03/14 現在の最新版は 0.8.0 です).
このファイルを展開し, lib 以下のファイル・ディレクトリを Ruby ライブラリの探索パスにコピーしてください. もしくは環境変数 RUBYLIB にこの lib ディレクトリを追加します. 以下の例では, 後者の方法でインストールを行っています.
インストール (Debian GNU/Linux の場合) に記述されるように APT のソースリストを更新し, 以下のコマンドで Ruby 用 MathML ライブラリを インストールしてください. (なお, libmathml-macro-dennou-ruby は TeX マクロの導入 で必要となるパッケージです).
% apt-get update % apt-get install libmathml-ruby libmathml-macro-dennou-ruby
では, 主プログラム 2 および モジュール 3 を再度ドキュメント化します. (コマンドプロンプトや DOS 窓を利用している方がコピペしやすいように, 改行しないものも載せておきます)
% rdoc -U integral03.f90 calc02.f90 --main integral \
--charset euc-jp --inline-source --ignore-case \
--title "integral Documents" --mathml
% rdoc -U calc02.f90 integral03.f90 --main integral --charset euc-jp --inline-source --ignore-case --title "integral Documents" --mathml
以下のようなページが生成されます.
自作の TeX マクロを登録することもできます. 以下に 電脳スタイル TeX マクロ の一部の数式に関連するマクロを抜粋したマクロファイルがあります.
このファイルをダウンロード後, <Ruby のパス>/math_ml/macro ディレクトリを作成し, そのディレクトリ以下にマクロファイルを置きます. 例えば, /home/hoge/rubylib ディレクトリに Ruby ライブラリの探査パスが 通っている場合には, 以下のようにマクロファイルを設置します.
% mkdir /home/hoge/rubylib/math_ml % mkdir /home/hoge/rubylib/math_ml/macro % cp D6math.sty /home/hoge/rubylib/math_ml/macro/
導入が完了したら, マクロファイルに登録されているコマンドをコメントに 記入してみましょう. 今回は偏微分を表記する "\DP" コマンドを 書き込み, rdoc コマンドでドキュメントを作成してみましょう.
! \[
! \DP{u}{t} + a \DP{u}{x} = 0
! \]
自作のコマンドを使用したい場合には, D6math.sty を参考に コマンドを作成し, マクロファイルを上記のように設置してください.
RDoc を用いて作成されたドキュメントをいくつか紹介します.
