Help us understand the problem. What is going on with this article?

GitbookでUMLの図入のドキュメントを書く

More than 3 years have passed since last update.

動機

ドキュメント書いてますか? 私は気分が乗ってくればさほど嫌いではありません。
とはいえMS-Wordはイライラするし、差分把握が出来ないのでやはりテキストベースでやりたいもの。そうなるとMarkdownがテッパンですよね。
Markdownで文書を書く場合、図の扱いに頭を悩ませます。特にプログラム設計の文書だとUMLの図が必要になることがあります、というところが動機です。

Dockerでさくっと動かせるようにしてあるので良かったら使ってみてください。
https://github.com/NewGyu/gitbook-uml

Gitbook

GitbookはMarkdownで文書を書いて公表するためのツールセットとサービスです。

  1. MarkdownをHTML,JSなどに変換するツールセット(ローカルでのプレビューもできる)
  2. ドキュメントを公開できるサービス https://www.gitbook.com/

オープンな文書であれば https://www.gitbook.com/ のアカウントを取得して、git pushすればあっという間にこんな感じの文書がホスティングされます。(有償プランで限定公開も可能です)

社内文書をGitbookで運用したい場合は、

  1. ツールセットでHTML,JSを出力
  2. 成果物を社内の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で即座に実行できるように用意しました。

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ファイルを書けば皆のところで動くので楽ですね。

NewGyu
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした