(9日目) sphinxcontrib-blockdiag の desctable を使ってみる

今日は sphinxcontrib-blockdiag の強力な機能、desctable を紹介します。

blockdiag シリーズはテキストから図を生成するツールですが、
ドキュメントというものは図だけで説明が完結するということは少ないです。
図に対する説明、各構成要素の説明などが図とペアになって必要とされることが多いと思われます。

sphinxcontrib-blockdiag の desctable 機能は、
ドキュメントに図を埋め込む際に補足情報として説明表を一緒に出力します。
desctable は description table を意味しており、図の各構成要素の説明を表形式にすることを指しています。

また、desctable はひとつの入力から図と表をセットで生成することで、
ドキュメントの不整合を防ぐことも目的としています。

desctable を使ってみる

では、desctable 機能を使ってみましょう。

desctable 機能を利用するためには、図に説明情報が埋め込まれている必要があります。
blockdiag シリーズでは、各ノードに description という属性が用意されていますので、
この description 属性に説明テキストを設定します。

{
  会員登録画面 -> 確認メール -> 入力画面 -> 確認画面 -> 完了画面, 完了メール;

  会員登録画面 [description = "会員登録のトップです。"];
  確認メール [shape = mail, description = "到達性の確認メールです。"];
  入力画面 [description = "会員情報を入力します。10フォーム程度を予定。"];
  確認画面 [description = "入力情報の確認。"];
  完了画面 [description = "完了後はログイン状態になっている。"];
  完了メール [shape = mail, description = "サンキューメール"];
}

では、この図を Sphinx 文書に埋め込みましょう。
通常通り blockdiag ディレクティブを利用しますが、その際に desctable オプションを指定します。

.. blockdiag::
   :desctable:

   {
     会員登録画面 -> 確認メール -> 入力画面 -> 確認画面 -> 完了画面, 完了メール;

     会員登録画面 [description = "会員登録のトップです。"];
     確認メール [shape = mail, description = "到達性の確認メールです。"];
     入力画面 [description = "会員情報を入力します。10フォーム程度を予定。"];
     確認画面 [description = "入力情報の確認。"];
     完了画面 [description = "完了後はログイン状態になっている。"];
     完了メール [shape = mail, description = "サンキューメール"];
   }

desctable オプションを指定すると図と共に図の説明表が生成されます。
説明表は description 属性の内容を含んだものです。

desctable を拡張する (numbered 属性)

desctable が表を作成する際に参照する属性の一つに numbered 属性があります。
numbered 属性はノードに番号をつけるためのものですが、
desctable はこの番号を表にも反映します。

.. blockdiag::
   :desctable:

   {
     会員登録画面 -> 確認メール -> 入力画面 -> 確認画面 -> 完了画面, 完了メール;

     会員登録画面 [numbered = 1, description = "会員登録のトップです。"];
     確認メール [shape = mail, numbered = 2, description = "到達性の確認メールです。"];
     入力画面 [numbered = 3, description = "会員情報を入力します。10フォーム程度を予定。"];
     確認画面 [numbered = 4, description = "入力情報の確認。"];
     完了画面 [numbered = 5, description = "完了後はログイン状態になっている。"];
     完了メール [shape = mail, numbered = 6, description = "サンキューメール"];
   }

numbered 属性を利用すると図と説明表を見比べやすくなります。

desctable を拡張する (attributes プラグイン)

blockdiag 1.0.3 から導入された attributes プラグインは desctable の説明表を拡張します。
attributes プラグインを利用すると、ノードの属性を新たに追加するとともに追加された属性を説明表に掲載します。

.. blockdiag::
   :desctable:

   {
     // ノードの属性 server, redundant, software を追加
     plugin attributes [server = 稼働サーバー, redundancy = 冗長性, software = 利用ソフトウェア];

     アプリ -> データベース, メッセージキュー, メールサーバ;

     アプリ [server = "web01,web02,web03", redundancy = "o", software = "Apache 2.2, PHP 5.3"];
     データベース [server = "db01", redundancy = x, software = "MySQL 5.5"];
     メッセージキュー [server = "db01" redundancy = x, software = "RabbitMQ"];
     メールサーバ [server = "mail01,mail02", redundancy = o, software = "Postfix"];
   }

この例のように各ノードに説明用の属性を追加することで、
ドキュメントとしての完成度があがりわかりやすいドキュメントが作れるようになります。

利用される例としては blockdiag の機能構成の説明や、
nwdiag や rackdiag における機器構成を記述するのに使われます。