RDocの使い方

RubyやRailsプロジェクトのドキュメント生成ツールには、ruby標準の RDocが便利です。
大規模な利用例としては、 Rails APIがあり、コードリポジトリから生成されているはずです。

標準ツールであるため、rubyをインストールすると付いてくるのですが、 jQueryの脆弱性の問題があったため標準バージョンでは適切に動作しない場合があります。
たとえばDebian busterのrubyパッケージの場合、jquery.jsが生成されず、コード表示できないという不具合があります。この場合、gemコマンドで新しいバージョンのrdocをインストールできます。

# gem install -N rdoc

セキュリティ対策済のバージョンでは、jqueryをインクルードせずに動作します。

マークアップ

rdocのマークアップは、公式リファレンスに記載があります。markdownと似ていますが、異なります。
リファレンスから読みとりづらい点として、コメントに行頭インデントを追加した行はコードブロックになります。サンプルコードの記述の際に必要です。

また、ドキュメント対象から除外する、といった制御命令も存在しており、読みやすいドキュメント整備のために順次導入すると良いでしょう。

rdocコマンドの使い方

rdocの基本的な使い方は以下のとおりです。

$ rdoc [--output some_dir] input_dir

input_dirにはプロジェクトディレクトリを指定します。rdocがコードを解析し、コメントをドキュメントとして整形します。Railsの場合には、多くの場合app/ディレクトリを指定する方が適切かもしれません。 --outputを省略した場合には、doc/ディレクトリに出力されます。

他のオプションについては、古いバージョンと挙動がかなり異なるため、rdoc --helpで確認した方が良いでしょう。

CSS追加

--template-stylesheets=./override.cssオプションで任意のCSSを追加できます。たとえば、デフォルトテンプレートのDarkfishはfloatのカラム実装であるため、以下のようなCSSを追加すると簡易レスポンシブ表示が可能です。

@media screen and (max-width: 1023px) {
    nav {
        float: none;
        width: 100%;
    }

    main {
        margin: 0 2em 5em 2em;
    }
}

文字色なども大部分は指定なしのため、追加の装飾が干渉なく効くように見えます。表示要素の変更を伴わないカスタマイズはCSSで相当調整できるでしょう。

その他のオプション

-x: excludeするpathを指定します。Railsプロジェクトでは、-x views -x assetsあたりが妥当でしょう
--page-dir: 非コードのドキュメントディレクトリ。このディレクトリはコードディレクトリの外であっても動作します。相対パス指定では動作せず、絶対パス指定すると動作するようです。また、メインのルートディレクトリとファイル名が重複しないようヘルプで注意表示があります
-m: トップページとしてインクルードするファイル名を指定します(パスではなくファイル名)。ターゲットディレクトリ外のドキュメントを指定する場合には、--page-dirオプションのPathに含まれていることが必要です

ドキュメントの配信

rdocで生成されたディレクトリは、スタティックサイトのHTML群になります。ドキュメントの配信はrdocのサポート範囲ではないので、何らかのHTTPサーバーを用いてファイル配信やアクセス制御を実装します。

テンプレート

rdocは外部テンプレート機能を持っていますが、生成ロジックの実装も必要になります。
また、流通しているテンプレートもほとんどありません。

たとえば Railsは sdocを利用しており、sdocをインストールすると"rails"というテンプレートを利用できます。

rdoc/generator/template/という名前空間にテンプレート一式を置くとカスタムテンプレートを実装できます。ディレクトリ名をsdoc -Tオプションで指定することで参照できます。
sdocのテンプレートはerbであるため、既存テンプレートを起点に比較的手軽に実装できるでしょう。