Pyxis のドキュメント生成

Pyxis のドキュメント生成では、EpyDoc と Sphinx を使っています。Pylons 0.9.6.1 のデフォルトでは Pudge を用いた仕組みが提供されているのですが、Pudge のメンテナンスが遅れている（古いバージョンのKidなどに依存している）ため、うまく動きません。

Sphinx は Python 2.6 における公式のドキュメンテーションツールで、Pylons でも最近 Pudge から Sphinx への乗り換えを行ったようです。

なぜ2つのドキュメンテーションツールを使っているかというと、EpyDoc がAPI リファレンスの自動生成用、Sphinx がマニュアル作成用だからです。ともに、reStructuredText で書いています。

Sphinx のインストール

easy_install でインストールできます。コードハイライトのための Pygments も合わせて入れましょう。

$ easy_install sphinx pygments

Sphinx の利用方法

sphinx のドキュメントルートを作成して、

$ sphinx-quickstart docs

ドキュメントが書けたら、build します。

$ sphinx-build docs html

これだけで、html 下にhtmlファイルが生成されます。

備考

生成されたページを見ると、デフォルトで検索画面が用意されています。

コンパイル時にjson 形式のインデックスを作成して、Javascript で検索しています。こういうやり方もあるんですね！

posted by id:junya_hayashi