(メモ) Module::Build による Perl ドキュメント生成
Module::Build
を使うとプロジェクトのドキュメント生成をビルドのタスクの一部として、かんたんなコマンドで実行できます。
./Build docs # blib/ 以下にドキュメント生成 ./Build html # blib/ 以下にHTML生成
Module::Build
でプロジェクトの対象ファイルを一元管理できるので、pod2html を直接叩くよりは楽だと思います。
ただし、内部モジュールのリンク解決ができなかったり、見た目の調整ができなかったりと、少し凝ったことをしようとするとハードルが高くなる印象です。
# やり方あるのかもしれませんが、設定方法もよくわからない。。
また、作った HTML をどこかにホスティングしたいと思うことがありそうですが、そちらは別途行わないといけないですね。
どうもこの辺りのドキュメント生成については、Java や Python など他の言語の方がエコシステムが成熟しているような気がします。
よいやり方があれば知りたいです。
参考
(メモ) Pod::Simple::HTML による Perl ドキュメントのカスタム生成
Pod::Simple::HTML
の POD に書いてある通りですが、Pod::Simple::HTML
を継承したクラスを作って、生成する HTML をカスタマイズすることができます。
例えば、do_pod_link
メソッドをオーバーライドすることで、L<...>
で記述するリンクタグの挙動を変更できます。
package My::PodParser; use parent 'Pod::Simple::HTML'; # override parent method sub do_pod_link { my ($self, $link) = @_; # Links local to our web site if ($link->tagname eq 'L' and $link->attr('type') eq 'pod') { my $to = $link->attr('to'); if ($to =~ /^My::/) { $to =~ s{::}{/}g; return "/docs/My/$to.html"; } } # All other links are generated by the parent class my $ret = $self->SUPER::do_pod_link($link); return $ret; }
上のように書くと、"My::" で始まるモジュールのリンク先は /docs/My/....html
となるので、ドキュメントをホスティングしているサイト上で適切に配置しておけば、独自モジュールのドキュメントでも相互にリンクさせることができます。
DarkPAN( *1,*2 ) などのドキュメントを運用する際に使えそうです。