日記/2013-07-18

python プログラムのドキュメンテーション †

仕事で python をいじることになってしまって，あわてて開発環境まわりを整備している． お仕事でやるわけなので，ドキュメンテーションは外せない．

で，クラス・メソッド・関数のリファレンスなんかのソースコードと対応するあたりは説明をソースコード内に書き込んだほうが間違いが少ないし，そういう説明部を抜き出して個別の文書ファイルを作成してくれるツールもある． こういうツールの起源は，クヌース生成の weave / tangle に遡るのかなぁ．

pydoc †

python 標準のドキュメンテーションツール． プログラム内に埋め込まれた docstring という文字列を抽出して文書化するもの． perl での perldoc みたいな立場なのかな．

困るところは

• unicode 文字列は受け付けない．エラーを吐く
• （非 unicode の）文字列だと表示は問題ないようだ．
  • pydoc コマンドでの端末出力も，問題ない
  • web サーバも問題無し
  • けど，これって python 2.x 系だとどうなのよ，ってのはある．たまたま運良く動いてるだけなんだろうな．
• pdf 出力できないのが困りもの

epydoc †

• 本家サイト http://epydoc.sourceforge.net/
• pydoc を拡張し，docstring 内に構文タグを埋め込めるようにしたもの．
• pdf 出力可能
• 野ざらし状態のプロジェクト
  • 最新リリースが 5 年前

sphinx †

• 本家サイト: http://sphinx-doc.org/
• 日本語サイト: http://sphinx-users.jp/doc10/index.html
• 最近はこちらが流行りらしい
• あまり調べてない

doxygen †

• 本家サイト: http://www.stack.nl/~dimitri/doxygen/
• 日本語サイト: http://www.doxygen.jp/
• 有名なドキュメンテーションツール
• C, Java などいろんな言語に対応
• docstring に対応
  • pydoc 同様，docstring をそのまま抽出するだけで，docstring 内では構文は使えない
• doxygen コメントも記述可能．
  • コメント内は @param などの構文を使える
• pdf 出力が可能

で，結局 †

コーディングルールの絡みもあって doxygen に日和ることに．