CircleCIのOrbsを利用して PlantUML のダイアグラムファイルをSVG (Scalable Vector Graphics)へ変換する Orb を作成しました。
この記事は作成したOrbについて解説します。
今回作成したOrb
CircleCI Orb Registry - orbss/plantuml
なぜこのOrbを作成したのか？
- 自分でPlantUMLサーバを準備したくなかった
- PlantUMLとRedmineを連携させたかった（他の記事でRedmineとの連携について書きます）
基本機能
- リポジトリで管理されているPlantUMLのダイアグラムファイルをSVGへ変換する(2019年1月29日時点で"png", "svg", "eps", "vdx", "utxt", "latex"への変換へ対応してます)
- 変換したファイルをCircleCIの Artifactsへ保存し閲覧出来るようにする
- CircleCIの persist_to_workspace 機能を使い他のworkflowsへ作成したSVGを渡せるようにする( オプション )
- 前回のコミットから更新があったファイルのみ変換する( オプション )
使い方
基本的な設置方法は こちら のリポジトリを参考にして下さい
PlantUMLを管理しているリポジトリへ「 .circleci/config.yml 」を配置します。以下は基本設定になります。
.circleci/config.yml
version: 2.1
orbs:
plantuml: orbss/plantuml@volatile
workflows:
version: 2
generator:
jobs:
- plantuml/generate-svg:
charset: UTF-8
persist_to_workspace: false
updated_files_only: false
オプション（現在はもっと増えてますので落ち着いたら書き直します）
詳しいオプションに関しては こちら を参考にして下さい。
| PARAMETER | DESCRIPTION | TYPE |
|---|---|---|
| extension | 変換するダイアグラムファイルの拡張子を指定する | string |
| persist_to_workspace | persist_to_workspaceオプションを有効にする | boolean |
| updated_files_only | 前回のコミットから変更があったファイルのみSVGへ変換する | boolean |
| workspace_root | persist_to_workspaceオプションのルートディレクトリ名 | string |
| workspace_path | persist_to_workspaceオプションのサブフォルダ名 | string |
SVGを生成する
リポジトリにPlantUMLダイアグラムファイルを追加しgit pushする事でCircleCIのArtifactsにSVGファイルが生成されます。
前回のコミットから更新があったファイルのみSVGへ変換するサンプル
こちらの リポジトリ を参考にして下さい。
その他制限事項
- PlantUMLダイアグラムファイルには必ず拡張子を付与する必要があります。
- ファイルはPlantUMLダイアグラムファイルが格納されている階層と同じ階層に作成されます。
- ファイルはリポジトリと同じ階層構造でArtifactsおよびworkspaceへ格納されます。
- 上記2つの挙動は変更できません。
- 現時点ではSVGファイルへの変換のみ対応しています。(2019年1月29日時点で"png", "svg", "eps", "vdx", "utxt", "latex"への変換へ対応してます)
- 「updated_files_only」オプション有効時、前回のコミットから更新されたPlantUMLダイアグラムが存在しない場合CircleCIのJobはエラーになります。
- ダイアグラムに日本語が含まれている場合はパラメータ「charset: UTF-8」を指定しないとエラーになります。
Todo
- SVGファイルだけでなく他のファイル形式にも対応させる(2019年1月29日 対応済み)
- PlantUMLコマンドのオプションを渡せるようにする（2019年1月29日 charsetのみ指定可能 他のパラメータも随時追加予定）
- 利用しているDockerイメージをPlantUML公式のものと置き換える
- フォントを指定してインストールできるようにする（現在はfont-ipaのみ対応、日本語のみ）
- 生成するファイルの大きさを指定できるようにする（主にサムネイル用途用のファイルの生成を考えている）
参考サイト
PlantUML公式サイト
シンプルなテキストファイルで UML が書ける、オープンソースのツール作成したCircleCI Orb
CircleCI Orb Registry - orbss/plantuml作成したCircleCI OrbのGitHubのリポジトリ
circleci-orbs-tm/plantuml | GitHubテスト用リポジトリ
blogs-tm/circleci_orbs_plantuml | GitHub