PlantUML 以外の diagram を AsciiDoc のドキュメントに埋め込んで見る（ditaa、C4 model 編）

Translate to English
https://translate.google.com/translate?sl=auto&tl=en&u=https%3A%2F%2Fksby.hatenablog.com%2Fentry%2F2021%2F02%2F03%2F222042

概要

記事一覧はこちらです。

前回からの続きです。今回は ditaa、C4 model の２つです。

参照したサイト・書籍

1. ditaa
   http://ditaa.sourceforge.net/

2. stathissideris / ditaa
   https://github.com/stathissideris/ditaa

3. ASCII Art Studio (Freeware)
   http://www.torchsoft.com/en/aas_information.html

4. Asciidoctor PDFとditaaと日本語の組み合わせに苦戦した話
   https://backport.net/blog/2019/09/21/asciidoctor_pdf_ditaa_japanese/

5. plantuml-stdlib / C4-PlantUML
   https://github.com/plantuml-stdlib/C4-PlantUML

6. The C4 model for visualising software architecture
   https://c4model.com/

目次

1. ditaa の diagram を埋め込む
   1. ASCII Art Studio をインストールする
   2. ASCII Art Studio で ditaa の diagram を作成し TXT ファイルを出力する
   3. AsciiDoc のドキュメントにファイルを include する
   4. asciidoctorWithMoveDiagSvg タスクを実行して動作確認する
2. C4 model の diagram を埋め込む
   1. https://github.com/plantuml-stdlib/C4-PlantUML#message-bus-and-microservices の C4 model with PlantUML のコードをファイルに保存する
   2. AsciiDoc のドキュメントにファイルを include する
   3. asciidoctorWithMoveDiagSvg タスクを実行して動作確認する

手順

ditaa の diagram を埋め込む

ASCII Art Studio をインストールする

ditaa は ascii art が画像ファイルになるユーティリティなので ascii art を書くのに便利なソフトがないか探したところ、ASCII Art Studio (Freeware) を見つけました。

http://www.torchsoft.com/en/download.html から ASCII Art Studio の English 版のインストーラをダウンロードしてインストールします。

インストールした ASCII Art Studio を起動すると以下のような画面が表示されました。

インストール直後はグリッドのサイズが小さかったので、メインメニューから「File」-「Settings...」を選択して「Settings」ダイアログを表示した後、「Font and Colors」タブで「Font size」を少し大きくしています。

ASCII Art Studio で ditaa の diagram を作成し TXT ファイルを出力する

http://ditaa.sourceforge.net/ に書かれている diagram をコピーしてもいいのですが、ASCII Art Studio を見つけたので自分で作成してみることにします。

適当に ascii art を書いてから、

src/docs/asciidoc/03_diagram の下に example-ditaa.txt を新規作成して、そこにコピペします。

コピペするとなぜか IntelliJ IDEA がチェックして赤波下線を表示していました。txt ファイルがチェックされる？

ファイルを選択してコンテキストメニューを表示させてから「Analyze」-「Inspect Code...」を選択してみると <option>, <uri reference>, RequirementsTokenType.EOL, RequirementsTokenType.IDENTIFIER or RequirementsTokenType.WHITE_SPACE expected, got '+' と表示されました。

Web で検索すると stackoverflow で PyCharm treats all txt files like requirements file を見つけました。どうも Requirements プラグインをインストールしていると requirements.txt と同じチェックが行われるらしいです。どうしようもなさそうなので何もしないことにします。

AsciiDoc のドキュメントに TXT ファイルを include する

src/docs/asciidoc/03_diagram/index.adoc に example-ditaa.txt を include します。

..........

== bytefield

[bytefield]
....
include::example-bytefield.clj[]
....

== ditaa

[ditaa]
....
include::example-ditaa.txt[]
....

AsciiDoc Plugin の preview にも Kroki のコンテナで生成された diagram が表示されますが、きれいな図になっていません。。。

asciidoctorWithMoveDiagSvg タスクを実行して動作確認する

asciidoctorWithMoveDiagSvg タスクを実行すると BUILD SUCCESSFUL が表示されて、

build/docs/asciidoc/03_diagram/index.html をブラウザで表示すると ditaa の diagram が表示されましたが、やっぱりきれいな図になっていませんね。。。

検索すると Asciidoctor PDFとditaaと日本語の組み合わせに苦戦した話 という記事を見つけました。どうも ditaa は日本語が含まれるとうまく出力してくれないようです。

C4 model の diagram を埋め込む

https://github.com/plantuml-stdlib/C4-PlantUML#message-bus-and-microservices の C4 model with PlantUML のコードをファイルに保存する

https://github.com/plantuml-stdlib/C4-PlantUML の Advanced Samples にきれいなサンプルがいくつもあるので、その中から Message Bus and Microservices のサンプルをコピペします。

src/docs/asciidoc/03_diagram の下に example-c4model.puml というファイルを作成してコピペします。PlantUML Plugin では diagram が表示されました。

AsciiDoc のドキュメントにファイルを include する

src/docs/asciidoc/03_diagram/index.adoc に example-c4model.puml を include します。

..........

== ditaa

[ditaa]
....
include::example-ditaa.txt[]
....

== C4 model with PlantUML

[plantuml]
....
include::example-c4model.puml[]
....

AsciiDoc Plugin の preview にも Kroki のコンテナで生成された diagram が表示されます。

asciidoctorWithMoveDiagSvg タスクを実行して動作確認する

asciidoctorWithMoveDiagSvg タスクを実行すると BUILD SUCCESSFUL が表示されて、

build/docs/asciidoc/03_diagram/index.html をブラウザで表示すると C4 model with PlantUML の diagram が表示されました。

履歴

2021/02/03
初版発行。