読者です 読者をやめる 読者になる 読者になる

AWS / PHP / Python ちょいメモ

amazon web service , PHP, Python を使ったときのメモ。日本語でググってもわからなかった事を中心に。

python, Django でドキュメント関連ツール

Django python ドキュメント Ubuntu

他の人が書いたコードを読む時に、全体像の把握がしたくなります。そこで、ソースからドキュメントが作れるツールをいくつか探してみました。

環境:

試用ツール

クラス図とコールグラスなどを生成:Doxygen

クラスの継承関係とかが把握できるドキュメントを生成してくれます。

Ubuntuの場合、次のコマンドだけでインストール完了。Graphvizは、Doxygen内で生成されるDOTファイルにもとづいて画像を生成するときに使われるコンポーネントのようです。

$ sudo apt-get install doxygen graphviz

次のような流れでドキュメントを生成できます。

$ doxygen -g  # 設定ファイルの生成

... 設定ファイル:Doxygen を編集...

$ doxygen  # 設定ファイルに基づき、ドキュメント生成
  • できた html は、こんな雰囲気。
    • f:id:hidehara:20150821091924p:plain


もとは C++ ソースのドキュメント生成だったようですが、いまでは多数の言語をサポートしていて python も対象になっています。設定ファイルの項目が多数あり、全部を把握するのは大変ですが、フロントエンド(Doxywizard)も用意されてるようなので、そちらを利用するのも手ですね。

Django admindocs

Djangoに同梱されているドキュメンテーションApp。Model などの定義やコメントを、動的にHTML形式で見れるようにしてくれます。admindocs というほどなので、Django admin と一緒に使います(必須かはわかりませんが、Django adminの右上にリンクが自動的に貼られる構成となっている)。

  • ドキュメント が表示される
    • f:id:hidehara:20150821091931p:plain


使い方は簡単で、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
    • f:id:hidehara:20150821092321p:plain
  • タグ (自分で拡張した templatetag もちゃんとでてきた!)
    • f:id:hidehara:20150821092339p:plain

公式ドキュメントはこちら。

locale エラー解消

一つ利用時に遭遇したのは、localeでのエラー 「ValueError: unknown locale: UTF-8」。

...
  File "/usr/local/lib/python2.7/dist-packages/docutils/utils/error_reporting.py", line 47, in 
    locale_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'でも大丈夫)。

その他のツール

まだ使ってないツールで pyreverse (pylint に同梱) , pydoc (定番?) というのもありました。Pyreverse はピンポイントで必要なクラス図を生成するには良さそうな感じ(設定しだいで色々できそうでもある)。pydoc は、man みたいな出力を手軽に作れるというイメージでしょうか。

まずは、今回つかってみた2種のツールを使って、いろいろ理解と整備を進めようと思います。