
RDocについて
RDocはコマンドラインから以下のようにして起動します。
1 |
% rdoc <options> [name...] |
ファイルをパースし、そこに含まれている情報を集めて出力します。
こうして全ファイルに渡るクロスリファレンスが生成できます。
もしnameがディレクトリならばその中を走査します。
nameを指定しなければ、カレントディレクトリとそのサブディレクトリ内の全てのRubyのファイルを処理します。
具体的な書き方とオプションコマンドについては下に書いていきます。
RDocの書き方
見出し
1 2 3 |
#= 見出しレベル1 #== 見出しレベル2 #=== 見出しレベル3 |
表示しない(コメントアウト)
1 2 3 |
#-- ~この間はRDocでは解釈されない~ #++ |
リンク
1 2 3 4 |
# http: # mailto: # ftp: # www. |
で始まるテキストはWEBへのリンクだと判別されます。
リスト
1 2 3 |
* リスト1 * リスト2 * リスト3 |
数字リスト
1 2 3 |
1. 数字リスト1 2. 数字リスト2 3. 数字リスト3 |
beginの書き方
1 2 3 |
=begin rdoc ~~~ =end |
太字、イタリック、タイプライター体
1 2 3 |
<b>太字</b> <em>イタリック</em> <tt>タイプライター体</tt> |
オプションコマンド一覧
optionsは以下が指定できます。
1 |
—accessor name |
nameで指定したメソッドをattr_xxxと同様なものとして取り扱います。
例えば”—accessor db_opt”とすると、以下のような行もドキュメントに含まれるようになります。
db_opt :name, :age
それぞれのnameには”=flagtext”というオプションを付けることができます。
例えば、”=rw”とするとattr_accessorと同じように取り扱われます。
1 |
—all |
プロテクティッドメソッドやプライベートメソッドも出力に含まれるようになります。
(デフォルトではパブリックメソッドのみです)
1 |
—charset charset |
生成するHTMLのcharsetを指定します。
1 |
—diagram |
モジュールやクラスを表示するのに図を使うようになります。
この機能は実験的なもので、すべての出力テンプレートに対応しているわけではありません。
dot V1.8.6かそれ以降がなければ”—diagram”オプションは正しい出力ができません。
1 |
—exclude pattern |
patternにマッチするディレクトリおよびファイルを処理の対象から取り除きます。
1 |
—extension new=old |
ファイル名の末尾が.newであるものを、末尾が.oldであるものとして取り扱います。
例えば’—extension cgi=rb’とすれば、RDocは”.cgi” で終わるファイルをRubyのソースとして取り扱います。
1 |
—fileboxes |
—diagramを指定した場合生成された図において、クラスがどのソースファイルで定義されているかを四角で囲うことで示します。
複数のファイルで定義されているクラスは複数の四角にまたがった図が作られます。
—diagramと一緒に使わなければ意味のないオプションです。(実験的な機能です)
1 |
—fmt fmt |
生成される出力を指定します。
1 |
—help |
使いかたの概要を表示します。
1 |
—help-output |
出力に関するオプションを解説します。
1 |
—image-format gif/png/jpg/jpeg |
図のフォーマットを指定します。
png、gif、jpeg、jpgが指定できます。
指定しなかった場合はpngが使われます。
—diagramが必要です。
1 |
—include dir,… |
:include:命令でファイルを探すディレクトリを指定します。
—includeを複数使ってもかまいません。
これを指定しなくとも 処理中のファイルはすべて探索されます。
1 |
—inline-source |
デフォルトでは、メソッドのソースコードはポップアップウィンドウで表示されます。
このオプションを付けると、インラインで表示されます。
1 |
-line-numbers |
ソースコードに行番号を付けます。
1 |
—main name |
最初に表示されるページに置かれるもの(クラス、ファイルなど)を指定します。
もし、特定のファイル(例えば、READMEなど)を置きたければ、それをコマンドラインの最初に置くだけでもかまいません。
1 |
—merge |
riの出力を生成するとき、出力ディレクトリにすでにファイルが存在すれば、そのファイルを上書きせずにマージするようにします。
1 |
—one-file |
すべての出力を一つのファイルに書きだします。
1 |
—op dir |
出力先のディレクトリをdirに設定します(デフォルトは”doc”です)。
1 |
—opname name |
出力の名前をnameにします(HTMLを出力する場合には何の効果もありません)
1 |
—promiscuous |
クラスやファイルが複数のファイルで定義されていて、ナビゲーション ペインのファイルの所をクリックした場合、そのモジュール内のクラスなどはそのファイルで定義されている分しか表示されません。
このオプションを指定すると、そのファイルで定義されているかどうかにかかわらず、すべてのモジュール(クラス)内モジュール(クラス)を表示します。
1 |
—quiet |
処理進行メッセージを表示しません。
1 |
—ri, —ri-site, and —ri-system |
ri で読める出力を生成します。
デフォルトでは—riを指定すると~/.rdoc に出力されますが、—ri-siteで$datadir/ri/
これれすべてはうしろに指定した —opを上書きします。
デフォルトのディレクトリはriのデフォルトのサーチ パスです。
1 |
—show-hash |
コメント内のnameというところからインスタンスメソッドへのハイパーリンク を生成します。
このオプションを指定しなければ’#’は取り除かれます。
1 |
—style stylesheet url |
(RDocのではなく)外部スタイルシートのURLを指定する
1 |
tab-width n |
タブの幅を指定する(デフォルトは8)
1 |
—template name |
出力生成時に使うテンプレートを指定する(デフォルトは’standard’)。
実際にはこれで$:の中のディレクトリのrdoc/generators/xxxx_templateが使われる。
1 |
—version |
RDocのバージョンを表示する
1 |
—webcvs url |
CVSのウェブフロントエンドへのリンクのURLを指定する。
URLが’\%s’を含んで いれば、そこがファイル名が置きかえられます。
‘\%s’ を含んでいなければ、ファイル名を指定したURLの後に付けたものを使います。