macにSphinx & Blockdiag環境を整える

そろそろドキュメント書きながら開発できる人間になりたい(´・ω・`)
ということで、SphinxとBlockdiagを使える環境を作る。

Sphinxはドキュメント生成ツールで、reST記法？で書くとhtmlとかpdfとかに簡単に出力できる。
ソースコードのdocstringも読み込んでドキュメントを作ってくれる便利ツール。
BlockdiagはPython製のブロックダイアグラムを生成してくれるツール。

インストール

まずは必要な物をインストール

php install sphinx blockdiag sphinxcontrib-blockdiag

ドキュメントプロジェクト作成

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

f:id:contaconta:20120620183257p:plain

うごいたー！
ライブラリのドキュメントでよく見るスタイルになっとる

これで快適ドキュメント生活ができるかもしれない（・∀・）

conta's diary

思ったこと、やったことを書いてます。 twitter: @conta_