GitBookをCircleCIでgh-pagesに公開

# はじめに
クラス図などドキュメントの更新が面倒だったので、GitBook,PlantUMLでドキュメントを作成し、CircleCIを使って自動ビルド&gh-pagesへのデプロイをしてみました。

### PlantUMLとは？
テキストからクラス図やシーケンス図などのUMLを生成するためのツールです。詳しくはhttp://plantuml.com/

```
@startuml
Class01 <|-- Class02
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 -- Class10
@enduml
```

![image.png](https://qiita-image-store.s3.amazonaws.com/0/109441/fb7511fb-26ea-4982-bcbc-9f25b2e5fc77.png)


# デプロイ環境の構築

## 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の登録
1. リポジトリの画面から「Settings」をクリックして設定画面へ
2. 「Deploy keys」をクリックしてDeploy Keyの登録画面へ
3. 「Add deploy key」をクリックして公開鍵を登録します。

<img width="742" alt="スクリーンショット 2017-08-29 1.58.13.png" src="https://qiita-image-store.s3.amazonaws.com/0/109441/b7ddb998-02e3-292f-6baa-bef69f4f11c4.png">


***Title***は自由な名前で大丈夫です。
***Key***には先ほど作成した```id_rsa.pub```の中身をコピー＆ペーストしてください。
***Allow write access***にチェックをつけるのを忘れないようにしてください。



## CircleCI
### プロジェクトの作成
1. [CircleCI](https://circleci.com/)へアクセス
2. 左のメニューから「Projects」へ
3. 「Add Project」をクリック
4. OSはLinuxのまま、設定したいリポジトリを探し「Setup project」をクリック
5. 一度、「Start building」をクリック

### Environment Variablesの設定
gh-pagesブランチにデプロイする際に利用する、ユーザーネームとメールアドレスを設定します。

1. CircleCIのプロジェクトの歯車アイコンをクリックして設定画面へ移動します。
2. 「Environment Variables」をクリックし設定画面へ移動します。
3. 「Add Variable」をクリック
4. ***Name***にUSERNAME、***Value***にGitHubのユーザー名を入力します。
5. 同じように***Name***にEMAIL、***Value***にGitHubのメールアドレスを入力します。
<img width="711" alt="スクリーンショット 2017-08-29 1.58.52.png" src="https://qiita-image-store.s3.amazonaws.com/0/109441/b42fdfdf-12fa-f539-358c-855f0bbf1a99.png">


### SSHキーの登録

1. プロジェクトの設定画面の「SSH Permissions」をクリックします。
2. 「Add SSH Key」をクリックします。
3. ***Hostname***に```github.com```, ***Private Key***に```id_rsa```の中身をコピー＆ペーストしてください。
<img width="720" alt="スクリーンショット 2017-08-29 1.58.27.png" src="https://qiita-image-store.s3.amazonaws.com/0/109441/57d20e23-a42b-740a-1bf0-79d27e2ccf72.png">


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```を作成し、以下のように記述します。

```book.json
{
  "plugins": ["uml"]
}
```

## CircleCIの設定ファイル
```circle.yml``` を作成し、以下のように記述します。

```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を追加します。

``` package.json
{  
  ...
  "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