【Rails】RDocを導入して自動ドキュメント生成をする方法【その2】

RDocについて

RDocはコマンドラインから以下のようにして起動します。

ファイルをパースし、そこに含まれている情報を集めて出力します。
こうして全ファイルに渡るクロスリファレンスが生成できます。
もしnameがディレクトリならばその中を走査します。
nameを指定しなければ、カレントディレクトリとそのサブディレクトリ内の全てのRubyのファイルを処理します。
具体的な書き方とオプションコマンドについては下に書いていきます。

RDocの書き方

見出し

表示しない(コメントアウト)

リンク

で始まるテキストはWEBへのリンクだと判別されます。

リスト

数字リスト

beginの書き方

太字、イタリック、タイプライター体

オプションコマンド一覧

optionsは以下が指定できます。

nameで指定したメソッドをattr_xxxと同様なものとして取り扱います。
例えば”—accessor db_opt”とすると、以下のような行もドキュメントに含まれるようになります。
db_opt :name, :age
それぞれのnameには”=flagtext”というオプションを付けることができます。
例えば、”=rw”とするとattr_accessorと同じように取り扱われます。

プロテクティッドメソッドやプライベートメソッドも出力に含まれるようになります。
(デフォルトではパブリックメソッドのみです)

生成するHTMLのcharsetを指定します。

モジュールやクラスを表示するのに図を使うようになります。
この機能は実験的なもので、すべての出力テンプレートに対応しているわけではありません。
dot V1.8.6かそれ以降がなければ”—diagram”オプションは正しい出力ができません。

patternにマッチするディレクトリおよびファイルを処理の対象から取り除きます。

ファイル名の末尾が.newであるものを、末尾が.oldであるものとして取り扱います。
例えば’—extension cgi=rb’とすれば、RDocは”.cgi” で終わるファイルをRubyのソースとして取り扱います。

—diagramを指定した場合生成された図において、クラスがどのソースファイルで定義されているかを四角で囲うことで示します。
複数のファイルで定義されているクラスは複数の四角にまたがった図が作られます。
—diagramと一緒に使わなければ意味のないオプションです。(実験的な機能です)

生成される出力を指定します。

使いかたの概要を表示します。

出力に関するオプションを解説します。

図のフォーマットを指定します。
png、gif、jpeg、jpgが指定できます。
指定しなかった場合はpngが使われます。
—diagramが必要です。

:include:命令でファイルを探すディレクトリを指定します。
—includeを複数使ってもかまいません。
これを指定しなくとも 処理中のファイルはすべて探索されます。

デフォルトでは、メソッドのソースコードはポップアップウィンドウで表示されます。
このオプションを付けると、インラインで表示されます。

ソースコードに行番号を付けます。

最初に表示されるページに置かれるもの(クラス、ファイルなど)を指定します。
もし、特定のファイル(例えば、READMEなど)を置きたければ、それをコマンドラインの最初に置くだけでもかまいません。

riの出力を生成するとき、出力ディレクトリにすでにファイルが存在すれば、そのファイルを上書きせずにマージするようにします。

すべての出力を一つのファイルに書きだします。

出力先のディレクトリをdirに設定します(デフォルトは”doc”です)。

出力の名前をnameにします(HTMLを出力する場合には何の効果もありません)

クラスやファイルが複数のファイルで定義されていて、ナビゲーション ペインのファイルの所をクリックした場合、そのモジュール内のクラスなどはそのファイルで定義されている分しか表示されません。
このオプションを指定すると、そのファイルで定義されているかどうかにかかわらず、すべてのモジュール(クラス)内モジュール(クラス)を表示します。

処理進行メッセージを表示しません。

ri で読める出力を生成します。
デフォルトでは—riを指定すると~/.rdoc に出力されますが、—ri-siteで$datadir/ri//siteに、—ri-systemで $datadir/ri//systemに出力されます。
これれすべてはうしろに指定した —opを上書きします。
デフォルトのディレクトリはriのデフォルトのサーチ パスです。

コメント内のnameというところからインスタンスメソッドへのハイパーリンク を生成します。
このオプションを指定しなければ’#’は取り除かれます。

(RDocのではなく)外部スタイルシートのURLを指定する

タブの幅を指定する(デフォルトは8)

出力生成時に使うテンプレートを指定する(デフォルトは’standard’)。
実際にはこれで$:の中のディレクトリのrdoc/generators/xxxx_templateが使われる。

RDocのバージョンを表示する

CVSのウェブフロントエンドへのリンクのURLを指定する。
URLが’\%s’を含んで いれば、そこがファイル名が置きかえられます。
‘\%s’ を含んでいなければ、ファイル名を指定したURLの後に付けたものを使います。