はじめに
クラス図などドキュメントの更新が面倒だったので、GitBook,PlantUMLでドキュメントを作成し、CircleCIを使って自動ビルド&gh-pagesへのデプロイをしてみました。
PlantUMLとは?
テキストからクラス図やシーケンス図などのUMLを生成するためのツールです。詳しくはhttp://plantuml.com/
@startuml
Class01 <|-- Class02
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 -- Class10
@enduml
デプロイ環境の構築
SSHキーの作成
CircleCIの秘密鍵はread-only
なのでread/write
な権限をもってる秘密鍵を登録します。
terminalで以下のコマンドを実行し、秘密鍵と公開鍵を生成します。
ssh-keygen -t rsa -b 4096 -C "メールアドレス" -f id_rsa
id_rsa
とid_rsa.pub
というファイルが出来ていれば成功です。
GitHub
リポジトリの作成
ドキュメントを管理するためのリポジトリを作成します。
※今回はpublicのリポジトリで作成しました。
Deploy Keyの登録
- リポジトリの画面から「Settings」をクリックして設定画面へ
- 「Deploy keys」をクリックしてDeploy Keyの登録画面へ
- 「Add deploy key」をクリックして公開鍵を登録します。
Titleは自由な名前で大丈夫です。
Keyには先ほど作成したid_rsa.pub
の中身をコピー&ペーストしてください。
Allow write accessにチェックをつけるのを忘れないようにしてください。
CircleCI
プロジェクトの作成
- CircleCIへアクセス
- 左のメニューから「Projects」へ
- 「Add Project」をクリック
- OSはLinuxのまま、設定したいリポジトリを探し「Setup project」をクリック
- 一度、「Start building」をクリック
Environment Variablesの設定
gh-pagesブランチにデプロイする際に利用する、ユーザーネームとメールアドレスを設定します。
- CircleCIのプロジェクトの歯車アイコンをクリックして設定画面へ移動します。
- 「Environment Variables」をクリックし設定画面へ移動します。
- 「Add Variable」をクリック
- NameにUSERNAME、ValueにGitHubのユーザー名を入力します。
- 同じようにNameにEMAIL、ValueにGitHubのメールアドレスを入力します。
SSHキーの登録
- プロジェクトの設定画面の「SSH Permissions」をクリックします。
- 「Add SSH Key」をクリックします。
-
Hostnameに
github.com
, Private Keyにid_rsa
の中身をコピー&ペーストしてください。
4.「Add SSH Key」をクリックして登録します。
ドキュメントの準備
ドキュメントを入れるためのディレクトリを作成します。
mkdir doc
作成したディレクトリへ移動し、npmで必要なツールをインストールします。
npm init -y
npm install gh-pages gitbook-cli gitbook-plugin-uml --save
gh-pages
nodeからgh-pagesブランチへpushするためのツールです。
gitbook-cli
nodeからgitbookを操作するためのツールです。
gitbook-plugin-uml
gitbookのビルド時に、Markdown内のplantUMLを画像に変換するgitbookのプラグインです。
plantUMLの書き方などは以下のサイトを参考にしてください。
https://plugins.gitbook.com/plugin/uml
http://plantuml.com/
プラグインを有効にするためにbook.json
を作成し、以下のように記述します。
{
"plugins": ["uml"]
}
CircleCIの設定ファイル
circle.yml
を作成し、以下のように記述します。
general:
branches:
only:
- master
machine:
node:
version: 6.2.2
test:
override:
- exit 0
dependencies:
pre:
- sudo apt install graphviz
override:
- npm install
deployment:
production:
branch: master
commands:
- git config --global user.name $USERNAME
- git config --global user.email $EMAIL
- npm run build
- |
cat <<EOF > ./_book/circle.yml
general:
branches:
ignore:
- gh-pages
EOF
- npm run publish
npm scriptを追加
package.json
に以下のscriptを追加します。
{
...
"scripts": {
"init": "gitbook init",
"start": "gitbook serve",
"build": "gitbook build",
"publish": "gh-pages -d _book -m 'Auto publish book'",
"deploy": "npm run build && npm run publish"
},
...
}
gitbookの初期化
terminalでnpm run init
を実行します。
README.md
とSUMMARY.md
が作成されます。
SUMMARY.md
は目次となります。
GitHubへPUSH!!
terminalでgit init
を実行し、gitを初期化します。
作成したリポジトリをremoteに追加してpushすればCircleCIが動きgh-pagesブランチにビルド後のファイルが置かれ公開されます。
最後に
毎回ドキュメントの更新が苦痛だったのですが、GitBookとCircleCIを使うことでだいぶ楽になりました。
ドキュメントがテキストーベースのMarkdownとplantUMLなので、更新履歴をGitで管理できるってのは使っていてとても便利だと感じました。
参考にしたサイトや記事
http://murajun1978.hatenadiary.com/entry/2016/07/01/232800
http://qiita.com/NewGyu/items/d35881166a2a70dee178