shellscript用のドキュメント生成ツールは、pythonやJavaとは異なりスタンダードなものがない印象があります。
（そもそもドキュメント生成される機会が少ないからかもしれない）
そこで、いくつか発掘したツールたちを並べておこうと思います。
尚、筆者も独自拡張付きのツールをいつか作ります（いつか）。
shocco.sh
Literate documentation tool for shell scripts (a la Docco)
公式HP: rtomayko.github.io/shocco
Coffee Script用のドキュメント生成ツール、 Doccoのシェルスクリプト版です。
マークダウンでの表記に対応しているようです。
ただしGithubではすでにアーカイブされており、 公式のフォローはもうない ようです。コミュニティで運営してるかもですが。
特定の構文はなく、人間が読みやすいように書くことができます。
公式HPとしてのせたURL先の文書もshoccoで生成されたようなので、見てみるとイメージがつかめるかもしれません。
| 表記スタイル | 書式なし Q&D |
| 変換先 | HTML |
| 出力 | stdout |
HeaderDoc
公式HP: HeaderDoc
Appleが使用している(していた)ツールです。
今は使われていないのか、ダウンロードページが消えています。
しかしMacでCommand Line Toolsを入れている場合は自動的に入ってい流ので使用することができます。
bashdoc
公式HP: bashdoc
JavaDocを基にして作られており、様々なタグをサポートしています。
bashdoc
公式HP:ajdiaz/bashdoc
同名の別実装です。
| 表記スタイル | 独自スタイル |
| 変換先 | HTML |
| 出力 | stdout |
表記スタイル
Githubには
このスクリプトはJavaプロジェクトにとってのJavadocのように振舞います
This script works similar to javadoc for java projects
とありますが、文法は独自なようです。
| # mod: modname | モジュール名 |
| # fun: funsignature | 関数の使用方法(パラメーター等) (但し説明はここには書かない) |
| # txt: | 前の定義(modかfun)の説明用テキスト |
| # opt: param: ... | オプションや関数へのパラメーターの説明 |
| # env: VAR: ... | VARと命名された環境変数への説明 |
| # use: ... | その関数やモジュールの使用例 |
| # api: ... | その要素に対してAPI名を指定。この名前を使って、最終的なドキュメントになんの関数やモジュールの説明を入れるか決めることができる |
TomDoc
Parse TomDoc'd shell scripts and generate pretty documentation from it
公式HP: tests-always-included/tomdoc.sh
Rubyのドキュメント生成ツールであるTomDocスタイルでコメントをかけるようにするツールです。
| 表記スタイル | TomDoc |
| 変換先 | mardown/plain text |
| 出力 | stdout |
RoboDoc
公式HP: RoboDoc