複数のプロジェクトのコードからドキュメントを自動生成する昨日やっていたことを振り返りながら今日の日付で日記を書きます。やってることは管理しているコード全体について、プロジェクトをまたいでドキュメントの生成を自動化する、というものです。ツールについての紹介ページがたくさん引っかかります。整形する作業を自動化しているだけで、コード中にちゃんとドキュメントを書いておかないといけないという意味では別に自動生成でもなんでもないわけです*1。コードとドキュメントが物理的に分離していないため、それぞれのバージョンの食い違いが発生しにくいというとても大きなメリットがあることも事実で、だからこそこれらのツールを使うわけです*2。ツールの実行も全部自動化してこその自動生成じゃないのか?と思いますわな。以下の条件でドキュメントを生成します。条件に合わなくても工夫すればなんとかなるかもしれません。用語とかが説明抜きにいきなり出てきますのでめげないでください。サーバ上のある位置に定期的に自動でドキュメントが生成される。対応したツールを扱いますが、それ以外のツール(言語)でも同様に応用可能だと思います。shスクリプトの例(Pdoc編)ではいきなりですがスクリプトを晒します。あってもなくてもいいです。手元の作業の都合上の問題です。置くためのディレクトリにもメモ用のファイルなどは置いておけるドキュメント生成先のディレクトリが存在しない場合は勝手に作る辺りでしょうか。できるだけメンテしなくても動くようにしたつもりですが、まだ甘いかもしれません。ディレクトリ構成ということで今回のサンプルのディレクトリ構成はこんな感じです。実行可能であることを表しています。作成しておくというものがあります。これが今回のキモというかほぼすべてです。気づいたと思いますが、内部向けしか考えていないので割と大胆なことになっています。ログも生成されたドキュメントも全部置いちゃう形にしてしまいました。作成する場所をドキュメントを置く場所と別に確保するのが面倒だったからに他なりません。考えるのが面倒でなければこのレイアウトにこだわる必要はまったくありません。なるかなんてことはまったく問題にならないのでお間違えなきよう。チェックアウト先の場所と名前がかぶりさえしなければなんだっていいですし、たぶんその方がブラウザで見たときには自然でしょう。なんて名前でなくたって何らかのプロジェクトについてのドキュメントであることは自明なんですから。サーバプロセスのユーザーでの実行権限があるとブラウザからドキュメントの自動生成ができます。便利なように見えなくもないですが、今回自分はそういうことが起きないように権限を分離しておきました。ないと誰かが閲覧中にいきなり裏でドキュメントの生成が走っちゃって、思いのほかサーバが重くなったりするかもしれないので。Indexesします。perlmod2www.plと言った具合に見えてほしくないものを除外していきます。ま、だいたいこんなもんでしょう。直アクセスすれば当然丸見えですが、細かいことは気にしちゃいけません。外に置くようにした方がいいです。場合は以下を削除してください。自身の作成したディレクトリかどうかを判断できますので、勝手にディレクトリを作ってもその中にドキュメントは吐き出してくれません。2>&1こんな感じでしょうか。オプションに与えるという処理を入れてやるのがよさげな気がします。1プロジェクト内でエンコーディングがぐちゃぐちゃに混ざってるなんてことはないでしょうから。自分とこではまだそこまでやってないのでとりあえず決め打ちですけど。パスは環境に応じて適当に直してください。コマンドを呼ぶ部分が以下のような感じになるはずです。以降じゃないとこの書き方はできないかも。いうディレクトリに置いてあるからこういう指定になっていますが、ここら辺は環境によって設定をいじってください。マニュアルとか参照してください。パスは環境に応じて適当に直してください。コマンドの呼び出し部分を以下のような感じにします。一式を丸ごと放り込むという大胆な設定の場合なので、どこに置いたかに応じて書き換えて使ってください。前提にしちゃってますが、これは以下の理由によります。認証情報をキャッシュしておかないと自動化できない誰の認証情報をキャッシュさせる?という問題が発生します。誰でもええやんと思うかもしれないけど、仮に誰かのアカウントにした場合、この自動生成のシステムが、いなくなった人のアカウントで動き続けようとするケースが考えられます。今一生懸命やっている人がいつまでもいるとは限りませんので、できるだけアカウント情報は残したくありません。管理用のアカウントにするという手もありますが、簡単に無認証にできるならそっちの方がいいかなと思いました。サーバ側の設定だけで、クライアント側であるこのスクリプトを置く機械の方では何もしなくていいかもしれません。ついては書いたまんまです。ディレクトリが作成された方が楽なんです。スクリプトの方には修正を加える必要がなくなります。共有などを利用して丸ごとコード全体をコピーしてくる場合は、コピー元をスクリプト側、あるいは他のツールで管理する必要が出てきます。スクリプト以外のツールで管理していると言えば管理しているのですが、この情報はディレクトリを移動してもそのまま生きますし、何らかの設定ファイルなどを書く必要がないというところがポイントです。利用していなくても自動化は可能です。(自分はやりたくないですが。)個々のツールの注意点PhpDocumentorまずインストールの段階で結構メモリを食います。利用できるメモリを増やしておきましょう。ドキュメント作成時にも実行時間、メモリの消費量とも大きいので、この設定はちょこちょこ見直す必要があるかもしれません。