Hatena::ブログ(Diary)

Basic このページをアンテナに追加 RSSフィード

2011-06-22

Sphinxでドキュメントを生成する

| 17:25 | Sphinxでドキュメントを生成するを含むブックマーク 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
  • 出力は下記のようになる。

f:id:rabbit2go:20110622125222p:image

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
  • 出力は下記のようになる。

f:id:rabbit2go:20110622125223p:image

LaTeXのように緻密なレイアウトは指定出来ないけれど、HTMLで素早く簡単に図面入りのドキュメントを作るという目的なら、非常に便利なツールだと思う。


関連

トラックバック - http://d.hatena.ne.jp/rabbit2go/20110622/1308731140