Sphinxでドキュメントを生成する
最近、Sphinxを使ってドキュメントを書いている。元々、Wordのようにチマチマと自分で文字のレイアウトや装飾を指定するタイプは好きではなく、LaTeXのように「プレーンテキストで文章を書いて、コマンド一発で出力を生成。レイアウト等は一切お任せ」型のシステムが好きなので、Sphinxはまさに好みのタイプと言える。
Sphinxのメリットを自分なりにまとめると次のようになる。
- 文書はプレーンテキストへ書く。実際の出力形態はSphinxへお任せ。
- 別ファイルに用意しておいた画像ファイルも取り込める。
- HTML形式だけではなく、PDF形式等での出力も可能。
- blockdiagやseqdiagなど、テキストで書いたコマンドで図面を生成して取り込み可能。
Windowsでの導入方法については下記のエントリが詳しい。
今回はMacで試してみた。動作環境は下記の通り
Sphinx
% sudo port install py26-sphinx % sudo ln -s /opt/local/bin/sphinx-build-2.6 /opt/local/bin/sphinx-build
- プロジェクトを作成する。（プロジェクト名やバージョンなどを聞かれるので適宜入力する）
% sphinx-quickstart
- 下記のコマンドでhtmlファイルを生成する。
% make html sphinx-build -b html -d _build/doctrees . _build/html Making output directory... Running Sphinx v1.0.7 loading pickled environment... not yet created building [html]: targets for 11 source files that are out of date updating environment: 11 added, 0 changed, 0 removed reading sources... [100%] src/unittest looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] src/unittest writing additional files... genindex search copying images... [100%] img/nunitresult.png copying static files... done dumping search index... done dumping object inventory... done build succeeded. Build finished. The HTML pages are in _build/html.
- _build/html/に一連のHTMLファイルが生成されている。
blockdiag
次にblockdiagを試してみる。これはSphinxからblockdiagを利用するためのものだ。
- 下記のコマンドでインストールする。
% sudo /opt/local/bin/easy_install-2.6 sphinxcontrib-blockdiag
- プロジェクト内のconf.pyに下記を追記する。
extensions = [...,'sphinxcontrib.blockdiag',...]
blockdiag_fontpath = '/Library/Fonts/Osaka.ttf' blockdiag_antialias = True
- 下記のようなブロック図をテキスト(.rst)に記載しておく。（テキストのインデントに注意）
.. blockdiag::
diagram forms {
Menu -> Show -> Change -> Apply;
Menu -> Help;
Menu -> List -> Update;
}
- 下記のコマンドでhtmlと図面を生成する。
% make html
- 出力は下記のようになる。
seqdiag
seqdiagも同様の形で利用出来る。
- 下記のコマンドでインストールする。
% sudo /opt/local/bin/easy_install-2.6 sphinxcontrib-seqdiag
- プロジェクト内のconf.pyに追記する。
extensions = [...,'sphinxcontrib.seqdiag',...]
seqdiag_fontpath = '/Library/Fonts/Osaka.ttf' seqdiag_antialias = True
- 下記のようなシーケンスをテキスト(.rst)に記載しておく。
.. seqdiag::
diagram {
User -> Program [label = "Launch"];
Program --> Service [label = "Create"];
Service --> Service [label = "Do stuff"];
Program --> Service [label = "Update"];
Service --> Service [label = "Do stuff"];
Program --> Program [label = "Clean up"];
}
- 下記のコマンドでhtmlと図面を生成する。
% make html
- 出力は下記のようになる。
LaTeXのように緻密なレイアウトは指定出来ないけれど、HTMLで素早く簡単に図面入りのドキュメントを作るという目的なら、非常に便利なツールだと思う。
関連
