読者です 読者をやめる 読者になる 読者になる

(2日目) blockdiag のインストール〜使い方 (Debian 編)

こんばんは、Sphinx & blockdiag アドベントカレンダー 2日目です。

昨日は Sphinx をインストールして使ってみるという流れを紹介しました。
今度は blockdiag を試してみましょう。

blockdiag とは?

blockdiag は僕こと @tk0miya が開発した画像生成ツールです。
テキストで定義された図を画像ファイルに変換することができます。
blockdiag は目的別にいくつかのパッケージに分かれています。

  • blockdiag
    • ブロック図、フローチャート、画面遷移図などを記述する
  • seqdiag
    • シーケンス図を記述する
  • actidag
    • アクティビティ図を記述する
  • nwdiag
    • ネットワーク系の図(論理ネットワーク図、ラック構成図)を記述する

ドキュメントの図を作る際は MS-Office (Excel, PowerPoint)、Visio、Cacoo、astah* など様々なツールを使いますが、
これらのツールと blockdiag シリーズが大きく異なる点として、
図のレイアウトは blockdiag が自動的に調整し、ユーザーは定義だけ意識すればよいと言うものがあります。

  • メリット
    • 図のメンテナンスが簡単 (定義を変えるだけ)
    • 他のツールと連携して自動生成もできる
    • 手間をかけずに作図できる
    • テキスト形式であるため扱いやすい
  • デメリット
    • レイアウトの微調整はできない
    • ツールが想定していない図を書くことができない
    • 定義方法を覚える必要がある

これらの特徴が生きてくるのは継続的に更新される図や
シンプルなドキュメントを素早く作りたいケースなどと考えています。


blockdiag はもともと図を書く機能を持たない Sphinx の補助機能として作られているの>で、
Sphinx と同じく UNIX 系の考え方に根ざしています。

blockdiag のインストール

blockdiag は 12/2 現在 Debian パッケージとしては提供されていませんが、
Debian JP の @mkouhei さんらの手によってパッケージングの準備が進められています。
おそらく次のリリースである wheezy にはパッケージが収録されると思いますので、楽し>みに待ちましょう:)


ここでは Sphinx と同様に easy_install を使ってインストールを行うのですが、
その前に依存パッケージである PIL (Python Imaging Library) をインストールします。
これはパッケージングされているので apt で入れてしまいましょう。

$ sudo apt-get install python-imaging

つぎに blockdiag をインストールします。
blockdiag は先ほどご紹介したとおり、目的ごとに 4つのパッケージに分かれていますの>で、
ひとつずつインストールします。

$ sudo easy_install blockdiag
$ sudo easy_install seqdiag
$ sudo easy_install actdiag
$ sudo easy_install nwdiag

また、Sphinx 連携用の sphinxcontrib-blockdiag パッケージ群も合わせてインストール>しておきます。

$ sudo easy_install sphinxcontrib-blockdiag
$ sudo easy_install sphinxcontrib-seqdiag
$ sudo easy_install sphinxcontrib-actdiag
$ sudo easy_install sphinxcontrib-nwdiag

さらに日本語を表示するために TrueType フォントをインストールします。
ここでは IPA フォントを利用します。

$ sudo apt-get install ttf-ipafont

ここはお好みに合わせて好きなフォントをインストールしてください。

コマンドラインから blockdiag を利用する

それではさっそく blockdiag を使ってみましょう。
まずはエディタを使って定義ファイルを作ってみましょう。

blockdiag {
  A -> B -> C, D;
}

この定義は

  • A から B へ遷移する
  • B から C と D に遷移する

という要素をもった遷移図です。

この定義ファイル(sample01.diag)を blockdiag コマンドで画像に変換してみます。

$ ls
sample01.diag
$ blockdiag sample01.diag
$ ls
sample01.diag   sample01.png

sample01.png という PNG 画像ファイルが生成されました。*1

定義通り "A から B"、"B から C と D" にそれぞれ遷移しています。

より細かい定義を覚えることでノードを装飾(色、形状、線、文字)したり、
グルーピングしたりすることができます。
これらを組み合わせると以下のような図を記述することができます。



また、ここでは blockdiag を中心に説明しましたが、
seqdiag や actdiag、nwdiag も利用することで幅広い図を作ることができます。

Sphinx にblockdiag の画像を埋め込んでみよう

ここまでは blockdiag 単体での使い方をご紹介しましたが、
ドキュメントは図だけでなく文章が必要となるケースがほとんどです。

blockdiag はコマンドライン用のツールとしてだけではなく、
様々なドキュメントツールと連携して図を文書に埋め込むことができます。

ここでは昨日設定した Sphinx で blockdiag の図を埋め込んでみましょう。
まず、Sphinx の blockdiag 連携機能の設定を行います。
Sphinx プロジェクトの設定ファイル conf.py を以下のように書き換えます。

# extensions 行に 'sphinxcontrib.blockdiag' などを追加する
# 既に他の拡張機能が入っていた場合は末尾に書き足してください。
extensions = ['sphinxcontrib.blockdiag', 'sphinxcontrib.seqdiag', 'sphinxcontrib.actdiag', 'sphinxcontrib.nwdiag']

# TrueType フォントへのパスを書く
blockdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'
seqdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'
actdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'
nwdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'

conf.py を書き換えるとドキュメント内で blockdiag ディレクティブが利用できるようになります。
たとえば index.rst に以下の記述を加えてみましょう。

.. blockdiag::

   {
     A -> B -> C, D;
   }

書き加えた後に make html を実行すると、書き加えたブロック図が HTML の中に埋め込まれます。


ここまでが blockdiag の基本的な使い方です。
より詳しい内容が知りたくなった方は blockdiag.com を見てみてください。

また、使い方が分からない場合や困ったこと、知りたいことがある場合は
メーリングリストTwitter の #blockdiag タグで質問するとよいでしょう。

*1:IPA フォント以外のフォン>トを利用している場合は -f オプションで TrueType フォントを指定してください