1. esehara@github

    Posted

    esehara@github
Changes in title
+SphinxでPythonドキュメントを自動的にビルドをゴリゴリドキュメント化
Changes in tags
Changes in body
Source | HTML | Preview
@@ -0,0 +1,40 @@
+# はじめに
+
+みなさんこんにちは!Python書いてますか? 現在Python + djangoを使ってサービスを作っているのですが、Pythonistaならお馴染みのとおり、Pythonにはdocstringというのが設定できるのを知っているかと思います。例えば、次のような簡単なスクリプトを動かしてみましょう。
+
+```py
+# -*- coding: utf-8 -*-
+from __future__ import print_function
+
+
+def foobar():
+ u"これは無意味な関数です。"
+ pass
+
+
+print(foobar.__doc__)
+```
+
+Pythonでは関数、クラス、メソッドで最初に現れた文字列リテラルを`__doc__`に代入し、あとからその関数の意味について調べることが出来ます。これは便利な機能ではあるのですが、しかしただPythonの対話型コンソール画面やIDE、あるいはPython向けの各種プラグインからしか引用できないとなると、とてももったいない。
+
+そこで、Pythonistaがよくつかう、`Sphinx`というドキュメントツールを使うと、このDocstringをまとめて一つにしてくれます。そのコマンドが`sphinx-apidoc`です。これの詳しい使い方については、[公式ドキュメント](http://docs.sphinx-users.jp/invocation.html#invocation-apidoc)を見ていただければと思います。上手くいけば、Sphinxのプロジェクトが立ち上がることでしょう。
+
+さて、テスト駆動をやる上において、[watchdog](https://github.com/gorakhargosh/watchdog)であったり、あるいは[sniffer](https://github.com/jeffh/sniffer/)にテストをフックして、ファイルが更新されるたびに、テストを起動している人も多いかと思われます。そこで、自分はdocumentもフックにして自動生成していたりします。
+
+以下はsnifferの例です。
+
+```py
+@runnable
+def execute(*args):
+ from subprocess import call
+ call('cd ../docs;make html', shell=True)
+ return call(
+ 'python manage.py test users --failfast',
+ shell=True) == 0
+```
+
+Linuxの場合ですと、`sphinx`は、`Makefile`を作り、`make`コマンドからドキュメントをビルドします。このようにフックを作っておくことによって、常に手元には最新のドキュメントが出来、そして意図しないreStのSyntax的な間違いがチェックできるようになります。
+
+ただ気を付けておくこととしては、`Git`で`.gitignore`のファイルとしてドキュメントディレクトリをいれていない場合、非常に鬱陶しいことになります。
+
+もちろん、Pythonのプロジェクトではなく、Sphinxのドキュメント生成性能がとても優秀であるが故に、別の言語のプロジェクトでつかっている人もいるでしょう。また、普通に資料を作るためにつかっている人もいるでしょう。そういうときに、`sniffer` + `sphinx`という組み合わせは非常に快適ですので、おすすめです。もちろん、ほかのファイル更新管理ツールを作ってもいいと思います。