PlantUMLで書いた図をCircleCIを使って自動で画像に変換する
同日
いろいろ試したり問題が起きたりしたから追記した
PlantUMLを使ってUML図を書くときはAtomにせよVSCodeにせよそれなりにビューアーがあるのでリアルタイムで見る分には基本問題ない
ただしドキュメントに挟むときとかあるいはメモがてら残したものをGitで管理して見たいときにちょいっと見るとなるといろいろめんどいしWebから見れない(ChromeのExtensionはあるけど)のでいっそ書いたら勝手に画像を残してくれる環境がほしいと思った。
CIにもよるが、今回はGitHubと連携が楽で無料の範囲でも結構いろいろ使えるCircleCIを使うことにした
さて同じようなことを考えている人がいるのではないかと思ったが、GitHub Pagesで公開する用途に使うケースが散見されるが単に画像だけ作って欲しいみたいなものは見当たらなかった(ちなみにその場合gh-pagesあたりが使えるらしい)
加えてだいたいCircleCI用の設定ファイルがCircleCI1.0のもので、2.0にするにはなんかいろいろと手間取ってしまった
設定ファイルそのものをさっくりまとめると
- plantUMLを入れる
- 日本語フォントを入れる
- 変換する
- コミットしてプッシュ
簡単にこれだけ。ただし前提条件を上げておくと
- 画像を用いるためgit-lfsを導入しておく(好みでもある)
- CIのプッシュをCI自身がスルーするためにコミットメッセージに[ci skip]を入れる
前提条件は後半に書いて先に必要だったところから
PlantUMLを入れる
apt-getで持ってこれるのでそんな難しい話ではない
sudo apt-get install plantuml
plantumlのjarファイルを直接持ってきてjava -jar plantuml.jar
で実行してもいい。その場合はgit-lfsの使用を推奨するがなくてもまあなんとかならなくもないと思う(最初それでやってたし)
日本語フォントを入れる
文字コードはUTF-8にする必要がある(と思われる。厳密には調べてない。ごめん)
ちなみに標準だと日本語フォントがないらしく豆腐現象が起きるので英語のみなら当然必要ない
sudo apt-get install [任意のフォントパッケージ]
当然だがパッケージがなければ別の方法でインストールすることになるので各々頑張ってね
ちなみに入れただけではそれを使ってくれるわけじゃないので設定する必要もある
コマンドラインから設定する方法もあると思われるが見つけられなかったのでUML図を書いているファイルに書き込む形をとる
@startuml "hogehoge" !include settingfile ~~~(略)~~~
そして設定ファイルを別に書く。ここでは!include settingfile
のとおりsettingfileの名前で以下を書き込む
skinparam{ defaultFontName [任意のフォント名] }
ちなみにフォント名がわからないときとかはplantuml -printfonts
ででてくるから一旦そのコマンドを走らせてもいいかも
変換する
plantuml filename.wsd
終わり。オプションを付けないとPNGで出力する。git-lfsとか使わないで全部テキストベースで管理したいなら-ttxt
とか-tutxt
オプションをつけるといいよ
ファイル名は *.wsd でやってしまっていいと思う。厳密に管理できるならそれに越したことはないが
コミットとプッシュ
コミット時には [ci skip]
のメッセージを入れておくこと(じゃないとpush時に自分のpushでCIが走ってまたpushして……と無限ループになる)
SSH鍵を渡していればプッシュは通常のコマンドと同様にやってくれるが、場合によっては画像ファイルの扱いでコンフリクトとかするのでオートコミット用のブランチを作って -f でプッシュしたりする必要がある(この辺改善できそう)
以上を踏まえ設定ファイルはこんな感じで
version: 2 jobs: document: docker: - image: circleci/openjdk:9.0.4 steps: # 専用のブランチ作成・移動 - run: git checkout -b auto-commit - run: sudo apt-get install plantuml - run: sudo apt-get install fonts-ipafont-gothic - run: plantuml doc/*.wsd - run: git add -A - run: git commit -am "[ci skip] auto commit" - run: git push -f origin auto-document
ここではフォントはIPAフォントを使っている(のと、git回りの設定やworking_directory関係の設定を省略しちゃってる)
コミットする内容がなかった場合はそのまま終了するように CircleCIの設定でProject Setting→Build Settings→Advanced Settings→Auto-cancel redundant buildsを有効にしてあげる必要がある(と思う、厳密にこれでうまくいくのか試しきれてない)
公式のドキュメントはこれ
ちなみにこれだと多分失敗時の処理とか全部スキップされるからwhen: on_fail
あたりを入れたりしないといけないはず
……とりあえずブランチを分けてフィルターを当てたほうが問題は起きにくい……かも
追記:
これでもこけた。一応「なにもしてない」ということになるので別に失敗でもいいのだが、失敗は失敗で放置しておくと本来の失敗で拾いそこねる可能性もあるのでどうにかしたい
余談だけど、curlやwgetが使えるなら(というかCircleCIは使える)PlantUML Text Encodingでエンコードして公式に変換してもらう方が楽だと思った
公式のオンラインエディタでも使ってるやつなので心配はないしDockerで自前で作ることもできる
エンコーディングの実装が必要になるほか、日本語フォントがあればの話になってしまうができるならそっちの方がいいかも
ここからは前提条件。本題のついでぐらいに
SSH鍵(いらないかも)
ssh-keygen してあげて pub をGitHub側に、秘密鍵をCircleCIの設定に。調べればわかるので問題ないと思う
Windowsだと面倒な気もするが、Bashコマンドですぐに作れる環境に行ける+そのままコマンド実行できるので覚えておくといいよ
書き込み権限が必要だと思ってたけどどうも用意した鍵の使用履歴がなかったのでいらないのかも
Git-LFSを入れる
まず作業環境に入れておく。入れておいてgit lfs track
コマンドで管理ファイルに*.pngを追加しておく
そんでCircleCI側も入るようにする
steps キーの下に以下を入れる。基本はDebian環境への導入と一緒
- run: curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash - run: sudo apt-get install git-lfs
すごいざっくりしてるしもっとうまくやれるところもあるかも知れないがとりあえずこんな感じ
やってる事自体は普通(手作業でも問題ないというか多分はやいぐらい)なのでこだわるところではないかも知れないが、後々ドキュメントの自動作成とかもできるようにしたいのでちょっとこだわった
自動でコミットした部分は別のブランチにしてあとからマージしてあげるのをイメージしている
できればブランチを分けてfilterかけてあげるとか、まだ変換してないところ&変更したものだけ変換とかもしたいが、とりあえずここまでできれば困ることはないので今後の改善点とCircleCIの勉強にもなると思いここまでとする。
なんかもっと楽にできるところとか問題が起きたときの回避策とか知ってる方いたら教えてください