java project에서 maven으로 asciidoctor-diagram 사용해보기

바로 이전 글에서 github이 markdown 문서에 mermaid를 지원하게 되었다고 소개했었다.

2022.02.16 - [Study/ETC] - Github markdown diagram 지원 소식

다만 github 사이트에서 markdown 문서 보기 할 경우만 지원이라 내가 만든 asciidoctor 문서에 mermaid를 사용해서 빌드할 수 없나 싶어 찾아보니 이미 있었다.

Asciidoctor Diagram 소개

https://docs.asciidoctor.org/diagram-extension/latest/

Asciidoctor Diagram - Asciidoctor Diagram

Asciidoctor Diagram은 Asciidoctor extension 중 하나인데 asciidoc 문서에 일반 텍스트를 사용하여 diagram을 추가할 수 있도록 도와준다.

장점과 단점이 있는데 우선 장점은 엄청 많은 확장을 지원한다.

잘 몰랐었는데 text to diagram을 도와주는 라이브러리가 많았다.

그런 라이브러리를 사용할 수 있게 Asciidoctor Diagram이 도와준다.

이 글을 쓰는 지금 이 시점에 지원하는 diagram type이 무려 34가지였다. (barcode는 문서 문법 오류로 잘못 표기된 듯)

Diagram Type	gif	pdf	png	svg	txt
a2s				✓
actdiag		✓	✓	✓
<barcode,barcode>>			✓		✓
blockdiag		✓	✓	✓
bpmn		✓	✓	✓
bytefield				✓
diagrams		✓	✓	✓
ditaa			✓	✓
dpic				✓
erd			✓	✓
gnuplot	✓		✓	✓	✓
graphviz		✓	✓	✓
meme	✓		✓
mermaid		✓	✓	✓
msc			✓	✓
nomnoml				✓
nwdiag		✓	✓	✓
packetdiag		✓	✓	✓
pikchr				✓
plantuml			✓	✓	✓
rackdiag		✓	✓	✓
seqdiag		✓	✓	✓
shaape			✓	✓
smcat				✓
svgbob				✓
symbolator		✓	✓	✓
syntrax (Syntrax)		✓	✓	✓
syntrax (JSyntrax)			✓	✓
tikz		✓		✓
umlet	✓	✓	✓	✓
vega			✓	✓
vegalite			✓	✓
wavedrom			✓	✓

이 중 mermaid가 flowchart, sequence diagram, class diagram, state diagram, erd, gantt, pie chart 같이 많은 diagram을 지원해주고 있고 그 외에도 barcode와 2d, 3d plot, network, packet header, railroad, UML, digital timing과 같은 diagram을 다른 diagram type들을 통해 사용할 수 있다.

vega의 경우 정말 다양한 시각화 문법을 제공하고 있고(예제 참고), mermaid는 심플하게 다양한 diagram을 만드는 방법을 제공하기 때문에 수많은 라이브러리 중 이 2가지를 관심 있게 보면 될 것 같다.

단점의 경우 단점이라고 말하기 애매하긴 한데 이러한 diagram type을 사용하는 건 당연히 각각의 diagram generator를 사용하는 것이고 asciidoctor diagram은 asciidoctor 빌드 시 diagram generator를 호출하여 특정 영역의 text 내용을 변환하여 출력되는 문서의 결과에 image로 교체하는 역할만 한다.

따라서 만약 asciidoctor diagram을 도입하고 문서에 사용하기 시작하면 해당 문서를 작성하는 모든 사용자들이 관련 diagram generator를 빌드하는 위치에서 설정하고 있어야 한다.

maven으로 dependency management 관리가 일원화되던 부분에 diagram generator 개별 설치라는 불편한 요소가 추가되는 것이다.

설정하기

maven 설정하기

기존에 asciidoctor를 이미 사용하고 있다고 가정하고 추가로 Asciidoctor Diagram을 설정하는 것을 설명한다.

기본적인 asciidoctor 설정의 경우 기존에 Spring Rest Doc 사용과 관련해 정리했었던 글을 참고하면 된다.

2019.06.14 - [Study/Java] - Spring Rest Docs 사용해보기

기존의 설정에 다음과 같이 추가한다.

<project ...>
    <properties>
        ...
        <asciidoctorj-diagram.version>2.2.1</asciidoctorj-diagram.version>
    </properties>
    ...
    <build>
        <plugins>
            ...
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                ...
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-diagram</artifactId>
                        <version>${asciidoctorj-diagram.version}</version>
                    </dependency>
                    ...
                </dependencies>
                <configuration>
                    ...
                    <requires>
                        <require>asciidoctor-diagram</require>
                    </requires>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

위와 같이 2가지 항목이 추가되면 된다.

asciidoctor-maven-plugin에 asciidoctor-diagram dependency를 추가하고 configuration에 requires 항목을 추가한다.

asciidoctor에서 제공하는 asciidoctor diagram example을 참고하고 싶은 경우 아래 링크를 참고하면 된다.

https://github.com/asciidoctor/asciidoctor-maven-examples/tree/main/asciidoctor-diagram-example

GitHub - asciidoctor/asciidoctor-maven-examples: A collection of example projects that demonstrates how to use the Asciidoctor M

diagram generator 설치하기

사용할 diagram type에 대해 asciidoctor 빌드 시 사용할 수 있도록 diagram generator를 설치해야 한다.

각 설치 링크는 위 diagram type 목록에 링크가 걸려 있다.

mermaid를 사용해보려고 경우 mermaid-cli 설치가 필요하다.

https://github.com/mermaid-js/mermaid-cli

GitHub - mermaid-js/mermaid-cli: Command line tool for the Mermaid library

어떻게 설치해서 빌드 시 사용할지는 선택의 자유다.

node를 통해 설치하고 사용할 수도 있고 어딘가 설치를 하고 path를 설정해서 사용할 수도 있다.

테스트로 사용하는 거라 npm g옵션으로 설치해서 사용해보았다. (global 옵션 사용은 mermaid-cli에서 권장하지 않는 옵션인데 그냥 사용했다.)

npm install -g @mermaid-js/mermaid-cli

asciidoc 문서 작성하기

이제 기존 문서에서 설정한 diagram을 사용하면 된다.

literal block에 몇 가지 attribute를 추가하여 사용하면 된다.

규칙은 다음과 같다.

[diagram-type, target=output-file-name, format=output-format]   
.... 
Diagram in appropriate syntax
....

mermaid를 사용하려고 하는 경우 아래처럼 사용한다.

[mermaid, mermaid-test, svg]
----
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
----

output-file-name을 설정하지 않으면 빌드 시 랜덤 한 이름의 파일이 생성되므로 지정해서 사용하는 것이 좋다.

(예: 'diag-13676221e2c9d6fd3ae951b78ea9acbf.png' 와 같은 이름의 파일이 생성됨, 재 빌드 시에도 이 이름이 유지되는 듯함)

그리고 block내의 text는 각 diagram의 문법을 참조해서 사용하면 된다.

이렇게 작성하고 빌드하면 아래처럼 diagram이 생성된다.

문서의 양이 많아질수록 빌드에 시간이 걸리기 때문에 실시간으로 diagram을 작성하면서 결과를 확인할 수 있는 live editor를 사용하면 좋다.

https://mermaid.live/

Online FlowChart & Diagrams Editor - Mermaid Live Editor

덧.

diagram generator를 여러 번 사용하니 해당 asciidoctor output directory에 .asciidoctor/ 라는 임시 directory가 생성된다.

생성된 이미지를 cache 처리하는 폴더인데 git commit 시 해당 directory는 커밋이 되지 않도록 .gitignore에 추가해주어야 한다.

.asciidoctor/