CircleCIでOrbsを利用しPlantUMLのダイアグラムをSVG (Scalable Vector Graphics)へ変換する

CircleCIのOrbsを利用して [PlantUML](http://plantuml.com "シンプルなテキストファイルで UML が書ける、オープンソースのツール") のダイアグラムファイルをSVG (Scalable Vector Graphics)へ変換する [Orb](https://circleci.com/orbs/registry/orb/orbss/plantuml#jobs-generate-svg "CircleCI Orb Registry - orbss/plantuml") を作成しました。

この記事は作成したOrbについて解説します。

## 今回作成したOrb

[CircleCI Orb Registry - orbss/plantuml](https://circleci.com/orbs/registry/orb/orbss/plantuml#jobs-generate-svg "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を渡せるようにする( **オプション** )
- 前回のコミットから更新があったファイルのみ変換する( **オプション** )

## 使い方

基本的な設置方法は [こちら](https://github.com/blogs-tm/circleci_orbs_plantuml "blogs-tm/circleci_orbs_plantuml | GitHub") のリポジトリを参考にして下さい


PlantUMLを管理しているリポジトリへ「 **.circleci/config.yml** 」を配置します。以下は基本設定になります。

```yaml:.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
```


## オプション（現在はもっと増えてますので落ち着いたら書き直します）

詳しいオプションに関しては [こちら](https://circleci.com/orbs/registry/orb/orbss/plantuml#jobs-generate-svg "CircleCI Orb Registry - orbss/plantuml") を参考にして下さい。

| 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ファイルが生成されます。

<img width="1440" alt="スクリーンショット 2019-01-24 22.17.23.png" src="https://qiita-image-store.s3.amazonaws.com/0/79373/24f782fc-f889-fbfa-4e03-be271780e5b1.png">

<img width="1440" alt="スクリーンショット 2019-01-24 22.17.30.png" src="https://qiita-image-store.s3.amazonaws.com/0/79373/b7d375b7-780b-02c7-07aa-f7df80d3ee20.png">

## 前回のコミットから更新があったファイルのみSVGへ変換するサンプル

こちらの [リポジトリ](https://github.com/circleci-orbs-tm/plantuml "circleci-orbs-tm/plantuml | GitHub") を参考にして下さい。

## その他制限事項

- 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]("https://pkgs.alpinelinux.org/package/edge/testing/x86/font-ipa")のみ対応、日本語のみ**）
- 生成するファイルの大きさを指定できるようにする（主にサムネイル用途用のファイルの生成を考えている）

## 参考サイト

- PlantUML公式サイト
[シンプルなテキストファイルで UML が書ける、オープンソースのツール](http://plantuml.com "シンプルなテキストファイルで UML が書ける、オープンソースのツール")

- 作成したCircleCI Orb
[CircleCI Orb Registry - orbss/plantuml](https://circleci.com/orbs/registry/orb/orbss/plantuml#jobs-generate-svg "CircleCI Orb Registry - orbss/plantuml")

- 作成したCircleCI OrbのGitHubのリポジトリ
[circleci-orbs-tm/plantuml | GitHub](https://github.com/circleci-orbs-tm/plantuml "circleci-orbs-tm/plantuml | GitHub")

- テスト用リポジトリ
[blogs-tm/circleci_orbs_plantuml | GitHub](https://github.com/blogs-tm/circleci_orbs_plantuml "blogs-tm/circleci_orbs_plantuml | GitHub")