1. この文書で伝えたいこと#
技術的／科学的な文書の作成では、ER図や組織図、シークエンス図など各種のダイアグラム(図版）がしばしば必要となることがあります。 ワードプロセッサなどを使ってWYSIWYGで作成することもできますが、 図版が複雑になるにつれ、位置調整などちょっとした変更の際にも、 GUIを使った煩雑な操作が必要になってしまいます。 テキストベースでこの様な図を記述することで、厳密な大きさや相対位置の管理が簡単になると期待されます。 また、プログラムによるデータに基づいた図の作成も視野に入ってきます。
また、文書のサイズが大きくなってくると、LaTeX , markdown, sphinx などの テキストベースの文書作成システムを利用して管理することが望ましい状況になります。 この場合にも、 図版も同じくテキストベースで管理できれば便利かつ効率的です。 テキストベースであれば文書の履歴管理も難しくありません。
この文書では、この様な各種のダイアグラム(図版)のうち私が触れた範囲での機能／使い方を概観していきます。 (図版を作成するためのコマンドは、この画面右上のダウンロードボタンをクリックして、 .rst をダウンロードしてご確認ください）
1.1. 汎用図版作成ツールの例#
現在も利用可能でかつよく利用されているテキストベースの汎用図版作成ツールには、
などがあります。これらのツールはいずれもテキストベースのソースから、 必要とする図版の画像ファイルなどを生成します。
また、文書作成ソフトのなかで、これらのプログラムのソースコードを 原稿に埋め込んで、完成文書に図を表示するためのプラグインが各種開発されています。 特にSphinx向けに上記のプログラムは全て拡張モジュールが利用可能です。
また、この他にも特定用途向けとして、
Pyreverse: Pythonのソースコードからクラス図を作成。 14 章
eralchemy: SQL のソースコードから ER 図を作成。 15 章
doxygen : C++/Pythonなどのソースコードからクラス図等を作成。 doxygen homepage
といったプログラムも存在します。これらのプログラムの場合は、 Python ソースコードやSQLで記述されたスキーマから図版ファイルを直接作成し、 sphinxなどに埋め込むということになります。また、これらのブログラムでは内部的に上記の 汎用図版作成システムを利用していることが多くあります。
1.1.1. Graphviz#
AT&Tによって開発されたGraphvizは、これらの汎用図版作成プログラムでは、最も古くから 存在していますが、現在も活発に維持／改良が行われています。 GraphvizではテキストベースのDOT言語を用いて、グラフをノードとそれらを繋ぐエッジと して表現します。 ここに揚げた図版作成システムはいずれもDOG言語の影響を受けた構文を 持っています。
Graphviz は 多数のノードとそれらを繋ぐエッジから構成されるグラフを効率的に 取り扱う各種の配置エンジンを持ったオープンソース ソフトウェアです。
Graphvizはsphinx環境に統合するための拡張 sphinx-graphvizも提供されており、 nsphinx環境では一つのソースファイル内に図版作成のための記述もまとめておけます。
Graphvizはフレキシブルにノードとエッジを自動的に配置してくれ,多彩なグラフの表示を 標準で提供していますが、組織図や家系図などのダイアグラムはあまり得意ではありません。
1.1.2. blockdiagとその仲間#
sphinxでは、blockdiagと呼ばれる作図ソフトもよく使われています。 blockdiagはDOT言語に触発されていますが、全く独立に開発された日本発のオープンソースソフトウェアです。 日本語でのドキュメントが豊富なのは便利なところです。
図版タイプ |
モジュール |
ブロック図 |
blockdiag |
シーケンス図 |
seqdiag |
アクテビティ図 |
actdiag |
ネットワーク図 |
nwdiag |
ラック構成図 [1] |
rackdiag |
パケット構成図 [1] |
packetdiag |
を作成するツールが提供されています。
1.1.3. mscgen(Mscgen: A Message Sequence Chart Renderer)#
mscgen[4 章]はその名前 "A Message Sequence Chart Renderer" が示す様に、 ネットワークプロトコルのようなメッセージシークエンスを表示するために 作成されました。 GPLで配布されています。最終更新版は2011年3月に公開されたバージョン0.20と なっています。 Unixexなシステムであれば問題なく利用かのうですが、後で見る様に、PlantUMLでも 同様の図版を生成することができますので、今後はmscgenそのものを使うことはないでしょう。
1.1.4. PlantUML PlantUMLとは#
PlantUMLはgraphvizをバックエンドに使い[2]各種のダイアグラムを作成する オープンソースのソフトウェアです。 サポートされている図の種類はGraphviz, blockdiagに比べても豊富です。 開発言語はJavaで、Linux/Windows/macosなどの各種プラットフォームで動作します。
このドキュメントでは、このPlantUMLの使い方をGraphvizやblockdiag との比較も交えて、紹介していきます。
1.1.5. その他#
著者は試していませんが、類似のプログラムに MermaidJSというのがあるようです。 MarmeidJSはMarkdown記法を使うということで、 Markdownでドキュメント管理している場合は、大きなメリットがありそうです[3]。 MermaidJSのsphinxのなかで使うためのパッケージも開発されています(sphinxcontrib-mermaid)。