python, Django でドキュメント関連ツール
他の人が書いたコードを読む時に、全体像の把握がしたくなります。そこで、ソースからドキュメントが作れるツールをいくつか探してみました。
環境:
試用ツール:
クラス図とコールグラスなどを生成:Doxygen
クラスの継承関係とかが把握できるドキュメントを生成してくれます。
Ubuntuの場合、次のコマンドだけでインストール完了。Graphvizは、Doxygen内で生成されるDOTファイルにもとづいて画像を生成するときに使われるコンポーネントのようです。
$ sudo apt-get install doxygen graphviz
次のような流れでドキュメントを生成できます。
$ doxygen -g # 設定ファイルの生成 ... 設定ファイル:Doxygen を編集... $ doxygen # 設定ファイルに基づき、ドキュメント生成
- できた html は、こんな雰囲気。
もとは C++ ソースのドキュメント生成だったようですが、いまでは多数の言語をサポートしていて python も対象になっています。設定ファイルの項目が多数あり、全部を把握するのは大変ですが、フロントエンド(Doxywizard)も用意されてるようなので、そちらを利用するのも手ですね。
Django admindocs
Djangoに同梱されているドキュメンテーションApp。Model などの定義やコメントを、動的にHTML形式で見れるようにしてくれます。admindocs というほどなので、Django admin と一緒に使います(必須かはわかりませんが、Django adminの右上にリンクが自動的に貼られる構成となっている)。
- ドキュメント が表示される
使い方は簡単で、adminをすでに使ってる人だとすぐだと思います。
- settings.py の INSTALLED_APPS に django.contrib.admindocs を追加
- urls.pyなどで定義してるurlpatternsに (r'^admin/doc/', include('django.contrib.admindocs.urls')) を追加
- 注意点としては r'^admin/' の定義よりも「前」に書くこと
- Pythonのdocutils モジュール (http://docutils.sf.net/) をインストールする
こんなページが表示されます。admindocs というよりも developerdocs 的な感じでしょうか?(admin = メンテする人という位置づけか)
- index
- タグ (自分で拡張した templatetag もちゃんとでてきた!)
公式ドキュメントはこちら。
locale エラー解消
一つ利用時に遭遇したのは、localeでのエラー 「ValueError: unknown locale: UTF-8」。
... File "/usr/local/lib/python2.7/dist-packages/docutils/utils/error_reporting.py", line 47, inlocale_encoding = locale.getlocale()[1] or locale.getdefaultlocale()[1] File "/usr/lib/python2.7/locale.py", line 543, in getdefaultlocale return _parse_localename(localename) File "/usr/lib/python2.7/locale.py", line 475, in _parse_localename raise ValueError, 'unknown locale: %s' % localename ValueError: unknown locale: UTF-8
僕の環境だとロケールの環境変数が LC_CTYPE=UTF-8 のみで、国に関する情報がないのが原因のよう。次のようにコマンドいれるか、.bashrcなどで永続化することで解決 (LC_ALL='C'でも大丈夫)。
- export LC_ALL='ja_JP.UTF-8'
- sphinx で ValueError: unknown locale: UTF-8 というエラーが出た - Please Sleep