Plant UMLを使用してディレクトリ構成図を書いた話
こんにちは。
現在母方の実家にきていますが、茨城は寒いですね。
学生時代も茨城に住んでいましたが、寒暖差が激しすぎて
四季を楽しむ余裕が無かった気がします。
さて今日は今年の仕事納めでPlant UMLなるものを知り、多少書き方を学んだので
その話をしようと思います。
背景
仕事最終日、特に急ぎの仕事もないのでずっと作ろうと思っていた業務マニュアルを
作成することにしました。
業務マニュアルを作成する過程で、ディレクトリ構成図を描く必要がありました。
めんどくさいなと思いながらパワポでポチポチしていたら、先輩に
「Plant UML使ってみれば」と提案され、
なんじゃそらと思っていると次のようなことを言われました。
・パワポでぽちぽちお絵かきってめんどくさいよね
・要素増えたりしたら位置移動が必要
・そもそも細かい図を作るのにPowerPointは向いてない
・パワポは絵心がない人間が作ると視認性が低くなる
・そんなときは、、ﾀﾘﾗﾗｯﾀﾗ〜〜〜〜〜〜
Plant UML〜〜〜〜〜〜〜〜〜〜！（
Plant UMLとは
PlantUMLはオープンソースのUMLダイアグラム作成用のテキストベースの言語である。PlantUMLの言語はドメイン固有言語の一例である[4]。ダイアグラムの表示にはGraphvizを使用している。
だそうです。
細かい図（ダイアグラム）を描画することに特化した言語みたいです。
コードを書くと自動的に図が描画され、配置やらなんやらはよしなにやってくれます。
オプションを使うことで、自分で配置や色をカスタマイズすることもできるようです。
シーケンス図や構成図などなど、エンジニア御用達のあんな図こんな図を
コードを書くだけでサクサク描けるようです。
使い方に関しては、先人が書いてくださっているのでそちらをご参照ください。
Plant UMLというパッケージを入れれば、vscodeで書いてすぐにプレビューできます。
描いたもの
私は今回、Ansibleに関してのディレクトリ構成図を書きました。
コードがこんな感じ。↓
@startuml
skinparam backgroundColor aliceblue
top to bottom direction
title Ansible_role構成図
frame "server#01" {
folder root
folder ansible_role {
folder roles {
folder role_name {
folder defaults {
file main.yaml as a
}
folder files {
file hoge.cfg
}
folder handlers {
file main.yaml as b
}
folder meta {
file main.yaml as c
}
folder tasks {
file main.yaml as d
}
folder templates {
file main.yaml as e
}
folder tests {
file main.yaml as f
}
folder vars {
file main.yaml as g
}
}
}
folder group_vars {
file group_vars.yaml
}
folder host_vars {
file host_vars.yaml
}
file ansible.cfg
file Playbook.yaml
file inventory.01
file inventory.02
}
root -- ansible_role
vars -[hidden]- meta
meta -[hidden] files
files -[hidden] handlers
handlers -[hidden] tests
ansible.cfg -[hidden]- Playbook.yaml
Playbook.yaml -[hidden]- inventory.01
inventory.01 -[hidden]- inventory.02
host_vars -[hidden]- group_vars
}
@enduml
で、実際描けた絵がこんな感じ。↓
ツリー構造を表現したいというよりは、
パッケージ図のようなイメージでAnsible_roleディレクトリの中身を説明するものが作成したかったので
このような描き方になりました。
つまづきポイント
カスタマイズ的な観点で言うと、思い通りにならないことが割とありました。
使い慣れてないってこともありますが、、
以下二点がつまづいたポイントです。
配置がイマイチな時がある
そのままオブジェクトを配置すると、オブジェクトの数が多い時などは
配置がイマイチな時があります。
以下は配置だけ行い、何もしない例です。
コードがこちら。
@startuml
skinparam backgroundColor aliceblue
top to bottom direction
title Ansible_role構成図
frame "server#01" {
folder root
folder ansible_role {
folder roles {
folder role_name {
folder defaults {
file main.yaml as a
}
folder files {
file hoge.cfg
}
folder handlers {
file main.yaml as b
}
folder meta {
file main.yaml as c
}
folder tasks {
file main.yaml as d
}
folder templates {
file main.yaml as e
}
folder tests {
file main.yaml as f
}
folder vars {
file main.yaml as g
}
}
}
folder group_vars {
file group_vars.yaml
}
folder host_vars {
file host_vars.yaml
}
file ansible.cfg
file Playbook.yaml
file inventory.01
file inventory.02
}
root -- ansible_role
}
@enduml
図が非常に横長になっていますね。
これは折り返すなどしてもっと図をコンパクトにしたい。
無駄なスペースにオブジェクトを置いてなるべく全体像を正方形に近づけたい。
これを
こうしたい
「Plant UML 折り返し」「Plant UML 改行」などで調べてみても
特にそれっぽい事例は出てきませんでした。（検索下手）
レイアウトのやり方で調べてみることに。
すると以下のページが見つかりました。
打倒！PlantUMLのなにこれレイアウトのその後 - VELTRA Engineering - Medium
おお…これこれ！これや！私がやりたかったんはこれや！
ページを飛ぶのがめんどくさい人向けに簡単に説明すると、
Plant UMLのレイアウトは相対的に行うものなので、オブジェクトを独立させた状態で動かす事は難しいのです。
なので、配置させたい位置の近くにあるオブジェクトにリンクを使って動かしたいオブジェクトを連結させ、
リンクを隠してしまえば一見独立した状態でそこに位置しているように見えると言う訳です。
文字で説明するのが難しいですね。上記の説明だとわかりづらいと思うので、図で説明すると
こんな感じです。
早速実行してみると…
~ root -- ansible_role #以下のコードを追加 vers -[hidden]- meta } ~
こうなりました！あとは、metaオブジェクトの横に連結させて同じようにリンクを隠せば…
~ root -- ansible_role vers -[hidden]- meta #以下のコードを追加 meta -[hidden] files files -[hidden] handlers handlers -[hidden] tests } ~
完成図です。
まだ図としては横長なので、group_versやhost_versなど他のオブジェクトも
縦にリンクを貼って図をコンパクトにします。
すると、上のような図になります。だいぶ、縦横比のバランスが良くなりました。
エイリアスとオプションは併用できない
マニュアルとして図を作成しているので、ファイル名の他に簡単な説明文なんかも
ファイルに書きたいと思いました。早速調べてみると、公式ページには
オプションをつけることでオブジェクトの中にテキストを入れることができるという
記述がありました。
説明文が長くなる場合は、オプションでテキストを [] の中に書くこともできます。
図の中でいう「main.yaml」の中身の説明文をファイルオブジェクトの中に書きたい
と思ったので、早速実行。
~
folder tasks {
file main.yaml as d [
メインで行うタスクを記述する
]
}
~こうしてみると、
syntax Errorになってしまいます。あれれ？と思いながらとりあえず
公式ページに書いてあるようにしてみると、、
~
folder tasks {
file main.yaml [
メインで行うタスクを記述
]
}
~
今度はちゃんとオプション内の説明文が表示された。
でも、オプションをつけるとファイル名は表示されなくなるらしい。
異なるディレクトリに配置されるmain.yamlという名称のファイルが複数存在するので、
名称をmain.yamlとしてエイリアスを適当にa,b..で割り振っていましたが、
エイリアスとオプションは併用できないようです。
ディレクトリ名は固有なので、じゃあディレクトリの説明文に
つけられないの？と試してみましたが
~
folder tasks {
メインで行うタスクを記述
file main.yaml
}
~~
folder tasks { [
メインで行うタスクを記述
]
file main.yaml
}
~
どちらも、syntaxErrorになってしまいました。
なるほどこういう書き方はできないのか、、
オプションを利用したいなら、識別子を固有にするしかないみたいですね。
もしくは、ノートオブジェクトをつけることもできますが、場所的にかさばりそうなので
今回は識別子を固有にして対応したいと思います。
ノートオブジェクトはこんなの↓
~
folder tasks {
file main.yaml
}
note bottom: コメント
~
以下、オプションを使用する際に注意する点まとめです。
・エイリアスとは併用できない。
・ファイル名を表示したい場合は、オプションの1行目にファイル名を記述する必要がある。
・入れ子構造にしているものに直接オプションをつける事はできない。
