ご無沙汰しております。技研の(ほ)です。
突然ですが、仕様書などの各種ドキュメントを作る際には、みなさんは何を使っていますか?
Sphinxのエディタ選択の際にも同じことを書いたのですが、私は今でもSphinxがベストだと思っています。
ただ、ベストだとは思っているのですが、インストール、設定、記法などのハードルの高さは確かに感じております。
そのため、今回はお手軽に使えそうな Gitbook を紹介したいと思います。
Gitbook
Gitbook は Markdown で書かれたドキュメントをHTMLやPDFなどで出力することができるサービスですが、Githubでソースが公開されているため、自分の開発環境にデプロイして使うことが可能です。
Sphinx VS Gitbook
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です。
1 2 |
npm install -g gitbook-cli |
Gitbookはnodeを使用するため、事前にnvm などを使用して “node” をインストールしてください。
もし、ubuntu のリポジトリに登録されている “nodejs” を使用する場合は、シンボリックリンクなどで “node” を作成してください。
12 sudo ln -s /usr/bin/nodejs /usr/bin/node
プロジェクト作成
下記のコマンドで helloworldディレクトリ下に Gitbook に必要なファイル(README.md, SUMMARY.md)が作成されます。
1 2 3 4 |
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にナビゲーションとして挿入されます。
下記のようにリンクのシンタックスを使用して記載してください。
1 2 3 4 5 6 7 8 |
# 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” ファイルに記載する必要があります。
1 2 3 4 5 |
# create config file vi book.json # install plugin gitbook install |
私は “book.json” は下記のようにしています。
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "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(数式記述)のためのプラグイン
HTML 作成
下記のコマンドで “_book” にHTMLが出力されます。
1 2 |
gitbook build |
EC2 環境では使えませんが、ローカルの場合には下記のコマンドでlocalhostで確認ができます。
12 gitbook --port 8080 serve
PDF 作成
EC2環境でPDFを作成するためには calibre と日本語フォントのインストールが必要です。
1 2 3 4 5 6 7 8 9 |
# 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 |
Jenkins
さて、ここまで来たらビルドなども自動でやりたくなりますよね。
私の場合は、HTMLはデプロイして公開、PDFはSlackへアップロードするため、下記のようなシェルを実行するようにしました。
(ファイル名やToken情報は変更しています。)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
#!/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エディタについて書きたいと思いますので、お楽しみに。