gitbookで楽々ドキュメント作成

ご無沙汰しております。技研の（ほ）です。

突然ですが、仕様書などの各種ドキュメントを作る際には、みなさんは何を使っていますか？
Sphinxのエディタ選択の際にも同じことを書いたのですが、私は今でもSphinxがベストだと思っています。

ただ、ベストだとは思っているのですが、インストール、設定、記法などのハードルの高さは確かに感じております。

そのため、今回はお手軽に使えそうな Gitbook を紹介したいと思います。

Gitbook

Gitbook は Markdown で書かれたドキュメントをHTMLやPDFなどで出力することができるサービスですが、Githubでソースが公開されているため、自分の開発環境にデプロイして使うことが可能です。

Sphinx VS Gitbook

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です。

Gitbookはnodeを使用するため、事前にnvm などを使用して “node” をインストールしてください。
もし、ubuntu のリポジトリに登録されている “nodejs” を使用する場合は、シンボリックリンクなどで “node” を作成してください。

sudo ln -s /usr/bin/nodejs /usr/bin/node

1 2	sudo ln -s /usr/bin/nodejs /usr/bin/node

プロジェクト作成

下記のコマンドで helloworldディレクトリ下に Gitbook に必要なファイル（README.md, SUMMARY.md）が作成されます。

ディレクトリ構成

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にナビゲーションとして挿入されます。
下記のようにリンクのシンタックスを使用して記載してください。

プラグインのインストール

標準のMarkdown記法だけで良ければプラグインは不要なのですが、数式やUMLを入れたい場合にはプラグインが必要になります。
使うプラグインは “book.json” ファイルに記載する必要があります。

私は “book.json” は下記のようにしています。

設定しているプラグインは下記です。
チャート類は書くのは大変ですが、修正差分が取りやすい点が良いと思います。
* sequence-diagrams : js-sequence-diagrams （シーケンス図）のためのプラグイン。
* flowchart : flowchart.js （フローチャート）のためのプラグイン
* plantuml : plantuml （UML）のためのプラグイン
* mathjax : mathjax（数式記述）のためのプラグイン

HTML 作成

下記のコマンドで “_book” にHTMLが出力されます。

EC2 環境では使えませんが、ローカルの場合には下記のコマンドでlocalhostで確認ができます。

gitbook --port 8080 serve

1 2	gitbook --port 8080 serve

PDF 作成

EC2環境でPDFを作成するためには calibre と日本語フォントのインストールが必要です。

Jenkins

さて、ここまで来たらビルドなども自動でやりたくなりますよね。

私の場合は、HTMLはデプロイして公開、PDFはSlackへアップロードするため、下記のようなシェルを実行するようにしました。
（ファイル名やToken情報は変更しています。）

どうでしょう。環境構築が簡単で、インストールにほとんど時間もかかりません。

これで好きなだけドキュメントが書けますね。
みなさんも試してみてください。

次回はGitbookの便利機能やGitbookエディタについて書きたいと思いますので、お楽しみに。