はじめに
Perl プロジェクトのソースコードに記された POD から、GNU make を使ってドキュメントを一括生成する方法を紹介します。
比較的シンプルな Makefile で実現できました。
プロジェクト構成例
プロジェクトの構成が、以下のようになっているとします。
.
├── bin
│ ├── bar.pl
│ └── foo.pl
└── lib
├── Foo
│ └── Bar.pm
└── Foo.pm
ドキュメント生成要件
ドキュメントは以下のルールで生成するとします。
- doc/ ディレクトリ以下に、ソースコードのパスを元に1ファイルずつ生成する
- pod2html コマンドを使って HTML 形式で出力
Makefile
Makefile をプロジェクトのルートディレクトリに配置します。
内容は以下のようにします。
.PHONY: html
GENHTML = pod2html
BINS = $(shell find bin -type f) # (1)
LIBS = $(shell find lib -name *.pm) # (2)
SRCS = $(BINS) $(LIBS)
DOCDIR = doc
HTMLS = $(SRCS:%=$(DOCDIR)/%.html) # (3)
html: $(HTMLS) # (4)
$(DOCDIR)/%.html: % # (5)
@if [ ! -e `dirname $@` ]; then mkdir -p `dirname $@`; fi # (6)
$(GENHTML) --infile $< --outfile $@
以下、この Makefile を少し詳し目に解説します。
(1) bin/ 以下の実行ファイルを展開します。
(2) lib/ 以下の .pm ファイルを展開します。
(3) 出力ファイルリストを $(SRCS) リストから生成します。
(4) メインの html タスクの設定です。出力ファイルすべてに依存します。
(5) 全出力ファイルに対する生成コマンドの設定です。
(6) ディレクトリがない状態で pod2html を実行するとエラーになってしまうので、予め作成しておきます。
実行結果
make を実行すると、以下のように各ソースコードに対して pod2html が実行されます。
% make
pod2html --infile bin/bar.pl --outfile doc/bin/bar.pl.html
pod2html --infile bin/foo.pl --outfile doc/bin/foo.pl.html
pod2html --infile lib/Foo/Bar.pm --outfile doc/lib/Foo/Bar.pm.html
pod2html --infile lib/Foo.pm --outfile doc/lib/Foo.pm.html
ソースファイルが更新されるまでは、make を再実行してもビルドは行われません。
% make
make: Nothing to be done for `html'.
doc/ 以下のファイル構成は以下のようになりました。
doc
├── bin
│ ├── bar.pl.html
│ └── foo.pl.html
└── lib
├── Foo
│ └── Bar.pm.html
└── Foo.pm.html
展望
Makefile を編集することでさまざまな拡張をすることができます。
例えば、pod2html に任意のオプションを加えて CSS を指定したり、pod2html 自体を別のコマンドに差し替えることも可能です。
あるいは、ドキュメントのリストページを生成するタスクを別途設定し、ドキュメント群と合わせてWebサーバでホスティングすることで、オンラインドキュメントを作ることもできるでしょう。
その他のやり方
今回紹介した以外で、Perl プロジェクトのドキュメントを生成する方法をいくつか挙げておきます。
他にもよいやり方をご存知の方はお知らせ下さい。
Module::Build のタスクとして実行する
下記を参照下さい:
(メモ) Module::Build による Perl ドキュメント生成 - weblog of key_amb
Daiku を使う
Daiku は Ruby の Rake にインスパイアされて作られた Perl 用のビルドツールです。
Rake の RDoc::Task のように、簡単にドキュメントを生成できる方法があるかはわかりませんが、Rake のようなインタフェースを持ち、任意コマンドも実行できるので、やってやれないことはなさそうです。
また、Daikufile(Makefile や Rake の Rakefile 相当)には Perl のコードが記述できるので、POD との相性はよさそうです。
まとめ
Perl プロジェクトのソースコードから、GNU make を使ってドキュメントを生成する方法を紹介しました。
参考
- GNU make について