macにSphinx & Blockdiag環境を整える
そろそろドキュメント書きながら開発できる人間になりたい(´・ω・`)
ということで、SphinxとBlockdiagを使える環境を作る。
Sphinxはドキュメント生成ツールで、reST記法?で書くとhtmlとかpdfとかに簡単に出力できる。
ソースコードのdocstringも読み込んでドキュメントを作ってくれる便利ツール。
BlockdiagはPython製のブロックダイアグラムを生成してくれるツール。
ドキュメントプロジェクト作成
sphinx-quickstart
と打って質問に答えていく。
conf.py
生成されたconf.pyにblockdiagを使うための設定を追加。
blockdiagで日本語を使いたかったら.ttfが必要らしい。IPAのサイトからフォントをDLして設定。
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinxcontrib.blockdiag'] # これ追加 blockdiag_fontpath = '/path/to/ipag.ttf'
サンプル
index.rstにBlockdiagのサンプルを書いてみる。
sphinx-quickstart on Wed Jun 20 17:32:10 2012. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to TestSystem's documentation! ======================================== Contents: .. toctree:: :maxdepth: 2 てすとー Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` .. blockdiag:: :desctable: blockdiag { 'あ' -> 'い' -> 'てすと' ; }
ビルド
➜ docs make html sphinx-build -b html -d build/doctrees source build/html Running Sphinx v1.1.3 loading pickled environment... done building [html]: targets for 1 source files that are out of date updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index Exception occurred: File "/Users/ogata/.pythonbrew/pythons/Python-2.6.7/lib/python2.6/site-packages/PIL/ImageFont.py", line 34, in __getattr__ raise ImportError("The _imagingft C module is not installed") ImportError: The _imagingft C module is not installed The full traceback has been saved in /var/folders/mx/jx26pzv53tx7dgw_ftg_vyk00000gn/T/sphinx-err-FClZmw.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>, or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks! make: *** [html] Error 1
あれー?
と思ったら、ここ(http://blockdiag.com/ja/blockdiag/introduction.html)にこう書いてあった。
~MacOSX (homebrew) の環境でインストールされる PIL パッケージは freetype2 に対応していないためそのままでは blockdiag を利用することはできません。また、freetype2 用の Foluma (パッケージ)は提供されていないため、 以下の内容で /usr/local/Library/Formula/freetype2.rb ファイルを作成します。
ということで手順どおりにやってPILをインストールしなおし!
$brew install freetype2 ... $pip install PIL -I ... -------------------------------------------------------------------- PIL 1.1.7 SETUP SUMMARY -------------------------------------------------------------------- version 1.1.7 platform darwin 2.6.7 (r267:88850, Jan 17 2012, 20:23:21) [GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)] -------------------------------------------------------------------- --- TKINTER support available --- JPEG support available --- ZLIB (PNG/ZIP) support available --- FREETYPE2 support available <== これでOk *** LITTLECMS support not available --------------------------------------------------------------------
よっしゃ!
再びmake
make html
うごいたー!
ライブラリのドキュメントでよく見るスタイルになっとる
これで快適ドキュメント生活ができるかもしれない( ・∀・)