SPHINX: PYTHON DOCUMENTATION GENERATOR を見る。SPHINX は、Georg Brandl 氏によって作られた Python プロジェクトのドキュメントを生成してくれるプログラム。reStructuredText のソースを HTML、Windows HTML Help、LaTeX、PDF といった出力形式で出力してくれる。reStructuredText のパースは、Docutils を使っているようだ。元は、Python Documentation のために作られて、他でも使えるように、きれいに書き直されたもののようだ。

対象となるのは、基本的には手で書かれた reStructuredText で、ソースから API のドキュメントを生成するような用途としては、Epydoc の方が向いているようだ。

動作環境は Python 2.4 以降で、ソースコードの自動ハイライトに関しては Pygments ライブラリが使われているので、これもインストールする必要がある。当然、docutils も必要。どちらも、ソースコードから setup.py でインストールすることもできるし、easy_install でインストールすることもできる。最新のバージョンは、Sphinx 0.1.61611。

インストールは easy_install を使えば、一発（docutils, sphinx, pygments)でインストールできる。

# easy_install sphinx

インストールしたら、

$ sphinx-quickstart

を実行すると、次々と質問されるので答えていくと、カレントディレクトリに Makefile と設定用ファイル conf.py と、サンプルの index.rst が作られる。これに加えて .build、.static、.templates も作られるが中身は空。sphinx-quicstart の実行中に最低限入力しなければいけないのは、"Project name", "Author name", "Project version"。それぞれ適当に入力する。その他は、とりあえずリターンで OK。

ちなみに、Separate source and build directories (y/n) で y と答えると、build 用のディレクトリ(build)とソース用のディレクトリ (source) が作られる。source ディレクトリの中には、サンプルの index.rst と、設定ファイルの conf.py が作られる。ソースと生成されたファイルは別ディレクトリの方がきれいかな（conf.py はドキュメントルートに作られるので、この場合は source に作られる）。

sphinx-quickstart で基本環境(Makefile 等)ができたら、次は、実際のドキュメントの生成。make をオプションなしに実行すると、何が指定できるのか分かる。

$ make

Please use `make <target>' where <target> is one of

  html      to make standalone HTML files

  web       to make files usable by Sphinx.web

  htmlhelp  to make HTML files and a HTML help project

  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter

  changes   to make an overview over all changed/added/deprecated items

  linkcheck to check all external links for integrity

とりあえず、

$ make html

とすると、.build/html にサンプルドキュメントが生成された。こんな感じで、なかなか色合い的にもかっこよくて見やすい。



「make htmlhelp」とすれば、Windows Help 用のファイルを .build/htmlhelp に生成してくれるので、これをヘルプコンパイラでコンパイルするとヘルプファイルができる。あるいは、make latex で .build/latex に latex ファイルと Makefile 作られているのでさらに make all-pdf で pdf を生成することができる。

また、

$ sphinx-build.py -b latex sourcedir builddir

のようにコマンドラインから出力形式やソースやビルド用のオプションを指定することもできる。

html の生成は、.templates に自分用のテンプレートを用意してもいいが、テンプレートは、Jinja テンプレートエンジンを使っている。Django templates に触発されて作られたというもので、似たような文法になっているらしい。

ちなみに Sphinx では標準の reStructuredText に加えて、Sphinx Markup Constructs があって独自の付加的なマークアップも使えるようだ。

最後に、Pygments は、Python だけでなく、ActionScript や Apacheconf から始まって、C や C++、Java、Ruby、Perl は当然のこと、Haskel や Lua などの言語やスタイルシートの類等、実に対応が広いシンタックスハイライトの生成をしてくれるようだ。

Python のコードであれば、次のような感じでハイライトしてくれる。

from pygments import highlight

from pygments.lexers import PythonLexer

from pygments.formatters import HtmlFormatter



code = 'print "Hello World"'

print highlight(code, PythonLexer(), HtmlFormatter())

Pygment: Introduction and Quickstart

コマンドラインから、

$ pygmentize test.py

みたいなこともいろいろできる（オプションを指定するとあれこれ）。pygmentize -f html -o test.html test.py みたいにすると、下のようなものが生成される。

タグ： python , sphinx , pygment

この記事のトラックバックURL：
http://tb.plaza.rakuten.co.jp/kugutsushi/diary/200803230001/ef048/