動機
ドキュメント書いてますか？ 私は気分が乗ってくればさほど嫌いではありません。
とはいえMS-Wordはイライラするし、差分把握が出来ないのでやはりテキストベースでやりたいもの。そうなるとMarkdownがテッパンですよね。
Markdownで文書を書く場合、図の扱いに頭を悩ませます。特にプログラム設計の文書だとUMLの図が必要になることがあります、というところが動機です。
Dockerでさくっと動かせるようにしてあるので良かったら使ってみてください。
https://github.com/NewGyu/gitbook-uml
Gitbook
GitbookはMarkdownで文書を書いて公表するためのツールセットとサービスです。
- MarkdownをHTML,JSなどに変換するツールセット（ローカルでのプレビューもできる)
- ドキュメントを公開できるサービス https://www.gitbook.com/
オープンな文書であれば https://www.gitbook.com/ のアカウントを取得して、git pushすればあっという間にこんな感じの文書がホスティングされます。（有償プランで限定公開も可能です）
社内文書をGitbookで運用したい場合は、
- ツールセットでHTML,JSを出力
- 成果物を社内のWebサーバーに配置
（弊社の場合はS3に配置しています）
ということになるでしょう。
ツールのインストールはNode.jsが入っていれば
npm install -g gitbook-cli && gitbook fetch 3.2.2
だけです。公式の説明やこちらの記事などを参考にすると良いでしょう。
PlantUML
UMLはastahを使って描いていたのですが、この場合、
- astahのファイルの管理
- PNG出力して配置
というところが手間でした。
この問題を解決する一つの手段として、UML自体もテキストベースで書き、UML図をコンパイルして生成するPlantUMLというものがあります。
UML図のレイアウトがいうこと聞かなかったり、そもそも記法を覚える必要があったり、確認するときにコンパイルして図を出力する必要があったり…とastahの素晴らしいGUI操作性と比べると面倒はあるのですが、
- UML図自体のDiffが把握できる
- プルリクでレビューできる
というところを重視してPlantUMLを採用しました。
GitbookとPlantUMLを組み合わせる
Gitbookにはgitbook-plugin-umlというプラグインがあるのでこれを利用します。
環境はDockerで即座に実行できるように用意しました。
- https://github.com/NewGyu/gitbook-uml/blob/master/Dockerfile
- https://github.com/NewGyu/gitbook-uml/blob/master/docker-compose.yaml
docker-compose up viewer を実行することで http://localhost:4000 でGitbookをローカルで確認することが出来ます。
AWS_PROFILE=プロファイル名 docker-compose up publish でS3に配置します。
http://gitbook.kinoboku.net.s3-website-ap-northeast-1.amazonaws.com/
必要なもの
Dockerを使えれば私の用意したDockerfile, docker-composeを使っていただければそれ以外何もいらないのですが、一応解説しておきます。
- Node.js 6系（4系でも良いと思いますが確認してません）
- Java8(JRE)
- graphviz
ハマりどころ
プラグイン名の微妙な違い
まず最初にgitbook-plugin-plantumlというプラグインをどこからか見つけてきて使っていたのですが、こちらは随分前のもので洗練されていませんでした。Forkして作られたgitbook-plugin-umlを使うと随分洗練されています。
日本語化ける
alpine-Linuxを使っていたからと言えるのですが、日本語フォントが入っていませんでした。
Graphvizが必要
Macの場合はgraphvizが必要ということでしたが、alpine-Linuxでも必要でした。
いやぁ、Dockerは誰かがこうしてDockerfileとcomposeファイルを書けば皆のところで動くので楽ですね。