ご無沙汰しております。技研の（ほ）です。
突然ですが、仕様書などの各種ドキュメントを作る際には、みなさんは何を使っていますか？
Sphinxのエディタ選択の際にも同じことを書いたのですが、私は今でもSphinxがベストだと思っています。
ただ、ベストだとは思っているのですが、インストール、設定、記法などのハードルの高さは確かに感じております。
そのため、今回はお手軽に使えそうな Gitbook を紹介したいと思います。
Gitbook は Markdown で書かれたドキュメントをHTMLやPDFなどで出力することができるサービスですが、Githubでソースが公開されているため、自分の開発環境にデプロイして使うことが可能です。
| Sphinx | Gitbook | |
|---|---|---|
| 記法 | reStructuredText | Markdown |
| 実行環境 | python | Javascript(node) |
| エディタ | as you like | 専用エディタあり |
GitbookはMarkdown記法なので、GithubやQiitaなどの普及により慣れた開発者が増えてきていると思います。
また、Atom や VisualStudio Code、StackEditなどのMarkdownのプレビューが標準で搭載されているエディタが多いだけでなく、Gitbookが専用のエディタを提供しています。
このGitbookエディタがとても良くできていており、Markdown記法を知らなくても書けるような機能もあります。
これで、Sphinxの時のようにエディタ探しの旅にでる必要もありません。
今回はAWS EC2 t2.small の ubuntu 16.04 環境で行っています。
t2.micro で運用した場合、メモリ不足で Gitbook の plugin の多くがインストールできないようです。
（そればかりか、同じ環境で動かしていたJenkinsが停止してしまいました）
あとからSWAPを足したりも面倒ですので、コスト的に問題なければ t2.small 以上を使った方が良いと思います。
インストールは下記のコマンドだけでOKです。
| npm install -g gitbook-cli |
Gitbookはnodeを使用するため、事前にnvm などを使用して “node” をインストールしてください。
もし、ubuntu のリポジトリに登録されている “nodejs” を使用する場合は、シンボリックリンクなどで “node” を作成してください。
| sudo ln -s /usr/bin/nodejs /usr/bin/node |
下記のコマンドで helloworldディレクトリ下に Gitbook に必要なファイル（README.md, SUMMARY.md）が作成されます。
| mkdir helloworld |
| cd helloworld |
| gitbook init |
Gitbookのプロジェクトは下記のような構成になります。
README.md, SUMMARY.md 以外は必要に応じて自分で作成することになります。
.
├── book.json (optional: configuration data)
├── README.md (required: Preface/Introduction for this book)
├── SUMMARY.md (optional: Table of Contents)
├── Glossary.md (optional: Lexicon/List of termes to annotate)
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md
ルートの README.md が index.html に変換されて、ドキュメントのトップページになります。
SUMMARY.md に記載の内容がHTMLにナビゲーションとして挿入されます。
下記のようにリンクのシンタックスを使用して記載してください。
| # Summary |
| * [Part I](chapter-1/README.md) |
| * [Writing is nice](chapter-1/README.md#writing) |
| * [GitBook is nice](chapter-1/something.md#gitbook) |
| * [Part II](chapter-2/README.md) |
| * [We love feedback](chapter-2/README.md#feedback) |
| * [Better tools for authors](chapter-2/something.md#useful-tools) |
標準のMarkdown記法だけで良ければプラグインは不要なのですが、数式やUMLを入れたい場合にはプラグインが必要になります。
使うプラグインは “book.json” ファイルに記載する必要があります。
| # create config file |
| vi book.json |
| # install plugin |
| gitbook install |
私は “book.json” は下記のようにしています。
| { |
| "plugins": ["sequence-diagrams", "flowchart", "plantuml", "mathjax"], |
| "pluginsConfig": { |
| "sequence-diagrams": { |
| "theme": "simple" |
| }, |
| "mathjax": { |
| "forceSVG": true |
| } |
| } |
| } |
設定しているプラグインは下記です。
チャート類は書くのは大変ですが、修正差分が取りやすい点が良いと思います。
* sequence-diagrams : js-sequence-diagrams （シーケンス図）のためのプラグイン。
* flowchart : flowchart.js （フローチャート）のためのプラグイン
* plantuml : plantuml （UML）のためのプラグイン
* mathjax : mathjax（数式記述）のためのプラグイン
下記のコマンドで “_book” にHTMLが出力されます。
| gitbook build |
EC2 環境では使えませんが、ローカルの場合には下記のコマンドでlocalhostで確認ができます。
| gitbook --port 8080 serve |
EC2環境でPDFを作成するためには calibre と日本語フォントのインストールが必要です。
| # install converter |
| sudo apt-get install calibre |
| # install Japanese font |
| sudo apt-get install fonts-ipafont-gothic fonts-ipafont-mincho |
| # install svgexporter |
| npm install -g svgexport |
| # create pdf |
| gitbook pdf |
さて、ここまで来たらビルドなども自動でやりたくなりますよね。
私の場合は、HTMLはデプロイして公開、PDFはSlackへアップロードするため、下記のようなシェルを実行するようにしました。
（ファイル名やToken情報は変更しています。）
| #!/bin/bash |
| # install gitbook plugin |
| gitbook install |
| # delete previous pdf |
| rm cresco-book*.pdf || true |
| filename=cresco-book-${GIT_BRANCH////-}-${BUILD_NUMBER}.pdf |
| echo $filename |
| # make html |
| gitbook build |
| # make pdf |
| gitbook pdf ./ ${filename} |
| # slack file upload setting |
| channel=gitbook |
| token=xoxp-XXXXXXXXXXX-YYYYYYYYYYY-ZZZZZZZZZZ-ZZZZZZZZZZZZZZZZZZZZZZZZ |
| echo $channel |
| echo $token |
| curl -F file=@${filename} -F channels=${channel} -F token=${token} https://slack.com/api/files.upload |
| # notify url to slack |
| content=http://xxxx.com/cresco-book/branch/${GIT_BRANCH////-}/index.html |
| payload='payload={"username":"Jenkins","text":"'${content}'"}' |
| curl -X POST --data-urlencode $payload https://hooks.slack.com/services/xxxxxxx/yyyyyyyyy/zzzzzzzzzzzzzzzzzz |
| # nginx root=/home/ubuntu/public |
| # /home/ubuntu/public/cresco-book/branch directory group is jenikns |
| rm -rf /home/ubuntu/public/cresco-book/branch/${GIT_BRANCH////-} || true |
| cp -r ./_book /home/ubuntu/public/cresco-book/branch/ |
| mv /home/ubuntu/public/branch/cresco-book/_book /home/ubuntu/public/cresco-book/branch/${GIT_BRANCH////-} |
どうでしょう。環境構築が簡単で、インストールにほとんど時間もかかりません。
これで好きなだけドキュメントが書けますね。
みなさんも試してみてください。
次回はGitbookの便利機能やGitbookエディタについて書きたいと思いますので、お楽しみに。
