読者です 読者をやめる 読者になる 読者になる

RDocでドキュメントを生成する

ドキュメントを生成する前にRDocをアップデートする場合は、
re RDocのアップデート - 祈れ、そして働け 〜 Ora et labora

とりあえず生成してみる

$ rdoc

.rbファイルがあるディレクトリに移動して、rdocコマンドを実行します。RDocを意識したマークアップをしていなくても、ソースコードとコメントを解析して、使えるドキュメントを生成してくれます。もしまったくコメントがなかった(マイガ!!)としても、ソースコードをからそれなりのドキュメントを生成してくれます。ドキュメントはカレントディレクトリに作成されたdocディレクトリに格納されます。

オプションを指定する

$ rdoc -c UTF-8 -t "Sample RDoc Document" -m README.rdoc

私がよく使うオプションの組み合わせです。

$ rdoc -c <文字コード> -t <タイトル> -m <デフォルトのページ> <対象ファイル>

対象ファイルにはドキュメントを生成する.rbファイルを指定します。ディレクトリを指定すれば、そのディレクトリ以下のすべての.rbファイルが対象になります。省略するとカレントディレクトリ以下のすべての.rbファイルが対象になります。

オプションの意味は次の通りです。

-c <文字コード> --charset=<文字コード> 生成するHTMLの文字コードを指定します。ソースファイルの文字コードと同じものを指定してください。
-t <タイトル> --title=<タイトル> 生成するHTMLのページタイトルを指定します。
-m <デフォルトのページ> --main=<デフォルトのページ> スタートページを指定します。ファイル名かクラス名を指定してください。

その他に、次のようなオプションもあります。

-a --all プライベートメソッドもドキュメントの対象に加えます。
-e --encoding=<文字コード> 生成するHTMLの文字コードを指定します。ソースファイルの文字コードを、読み込み時に指定された文字コードに変換します。--charsetと同時に指定された場合は--encodingが優先されます。
-w <タブ幅> --tab-width=<タブ幅> タブ幅を指定します。
-N --line-numbers ソースコードに行番号を含める、らしいのですが、指定しても違いがないため、指定していません。

毎回指定するオプションを環境変数に設定する

FILE: ~/.bashrc

export RDOCOPT="-c UTF8"

毎回指定するオプションは環境変数 RDOCOPTに設定しておくと、自動的に適用されます。

$ rdoc -t "Sample RDoc Document" -m README.rdoc

最終的にこんな感じで実行しています。