GitHub
CircleCI
plantuml
gitbook

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

デプロイ環境の構築

SSHキーの作成

CircleCIの秘密鍵はread-onlyなのでread/writeな権限をもってる秘密鍵を登録します。
terminalで以下のコマンドを実行し、秘密鍵と公開鍵を生成します。

ssh-keygen -t rsa -b 4096 -C "メールアドレス" -f id_rsa

id_rsaid_rsa.pubというファイルが出来ていれば成功です。

GitHub

リポジトリの作成

ドキュメントを管理するためのリポジトリを作成します。
※今回はpublicのリポジトリで作成しました。

Deploy Keyの登録

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

スクリーンショット 2017-08-29 1.58.13.png

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

CircleCI

プロジェクトの作成

  1. CircleCIへアクセス
  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のメールアドレスを入力します。 スクリーンショット 2017-08-29 1.58.52.png

SSHキーの登録

  1. プロジェクトの設定画面の「SSH Permissions」をクリックします。
  2. 「Add SSH Key」をクリックします。
  3. Hostnamegithub.com, Private Keyid_rsaの中身をコピー&ペーストしてください。 スクリーンショット 2017-08-29 1.58.27.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.mdSUMMARY.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