Griflet Build 基本的な使い方

はじめに

Griflet Buildは、GitHub上にホストされたRe:VIEWのプロジェクトをビルドして、生成されたPDFなどを一時保存しておくサービスです。

Re:VIEWを使用して原稿執筆を行う場合には、主に執筆の補助ツール、「CIツール」のように使っていただくことが可能となります。適切に設定していただければ、GitHubの「WebHook」の仕組みにより自動的に最新版のレポジトリに対応したPDF等をGrifletからダウンロードできるようになります。

「Griflet Build」と呼ばれるシステムの開発自体は、いわば「α版」に近いステータスにあります。各種のバグや、使いづらい点などについては技術書典スタッフ、特に開発責任者@amedamaまでお知らせください。

GitHub上のレポジトリを準備する

GitHub上のアカウントhansodesanで、「review_test_project」というGitHub上のレポジトリを新規作成しつつGriflet Buildのプロジェクトを設定する方法を説明します。

図はGithubの新規レポジトリ作成画面です。「Description」や「Public/Private」については、適宜必要な設定を行ってください。

出版まで原稿データを公開したくない場合は「Private」設定にすることになるでしょうが、GitHubアカウントがPrivateレポジトリを持てる状態(課金ユーザ)である必要があるでしょう。

なお後述する通り、現時点ではGriflet Buildはデプロイキーを通じてレポジトリ内のデータを取得します。よって「Private」のレポジトリであってもデータ取得上の問題は発生しません。

Re:VIEWツールにてreview-initでプロジェクトを作成する

ローカル環境にRe:VIEWツールをインストールしておき、review-initで初期テンプレートを作成します

続いてgit init等を実行して、GitHubに初期テンプレートをそのままアップロードします。

現在、Griflet BuildはRe:VIEW 2.2.0のプロジェクトだけに対応しています。

$ review-init --version  # バージョン確認を行います
review-init 2.2.0
$ review-init review_test_project
$ cd review_test_project
$ git init
$ git add .
$ git commit -m "First Commit"
(以下の"hansodesan/review_test_project.git"の部分はレポジトリ毎に異なります!)
$ git remote add origin git@github.com:hansodesan/review_test_project.git
$ git push -u origin master

Re:VIEWプロジェクトのの初期状態がそのままGitHubにアップロードされました。

ここからGriflet Buildにこのプロジェクトを登録します。

Grifletへサインアップする

トップページからGitHubアカウントでログインします。Twitterでもログイン出来ますが、GitHubプロジェクトと連携するにはGitHubアカウントでのログインが必要です。

GitHubのWebページ上にてOAuthの確認を行い、本サービスの利用規約を確認・同意をします。

アカウント情報を確認し、「トップページへ移動する」ボタンからトップページへ移動します。

プロジェクトを作成する

図のように「新規プロジェクト作成」ボタンが表示されるはずです。

このボタンを押して、Griflet上にGitHubと連携するプロジェクトの作成を開始します。

GitHubプロジェクトの指定

次の画面でオーナー名とレポジトリ名を指定します。 今回は「hansodesan」「review_test_project」となります。 2箇所のテキスト入力を行い、「作成」ボタンを押します。

参考: 高度な方法として、オーナーにGitHub上のグループを指定することも可能です。 ただしその場合、グループのメンバーであることがGitHub内で公開ステータスになっていなければなりません。

Griflet内でプロジェクトが出来上がったら

まず深呼吸して、作成成功後の画面の説明を注意深く読んでください。
ここで表示される「Griflet内でのプロジェクト作成成功」を示すページは、このあとGitHub側のプロジェクト設定を行う上で必要な情報を掲載しています。
一部の情報はあとから再確認出来ません。
あわてて画面を閉じたりしないようにしてください。

Griflet内でプロジェクトが出来上がったら、今度はGitHubのプロジェクト上で、大まかに2つ設定を行う必要があります。

  • デプロイキー(Deploy key)の設定
  • Webhookの設定

各情報についての詳細はGitHubのヘルプなどで確認してください。以下ではごく基本的な部分だけ説明します。

(GitHub設定画面上で) デプロイキーを設定する

GitHubのプロジェクトページ(今回は「hansodesan/review_test_project」)の設定画面(Settings)へ移動し、「Deploy keys」設定を開きます。

「Deploy keys」設定の「Add deploy key」ボタンを押し、そこでGriflet上で表示されていたデプロイキーを入力します。

「Key」と記載された広いテキスト入力フィールドにデプロイキー本体を入力します。 「Title」は本サービスであることがわかれば何でもよいでしょう。 今回はデプロイキー末尾にも記載されている「griflet@tbf.griflet.net」としています

「Allow write access」にチェックを入れる必要はありません。安全のため、チェックを入れないようにしてください。

以上、適切にデプロイキーについての設定ができたら「Add key」ボタンをクリックします

デプロイキーのFingerprintを確認する

Grifletのプロジェクト作成成功時の画面で、デプロイキーの下に「公開鍵のFingerprint」という情報が掲載されています。

念の為、Github上のデプロイキー(Deploy keys)に記載されているFingerprintの情報と一致しているか、確認してください。

Webhookを設定する

GitHubのプロジェクトページの設定画面(Settings)中、「Webhooks & services」設定を開きます。

そしてその画面中の「Add webhook」ボタンをクリックし、表示された画面中の「Payload URL」にGrifletのプロジェクト成功画面内に記載されたURLを入力します。

このとき、他の設定を変更する必要はありません (GitHub側のUIが変わらない限り)。具体的には次のような設定のままにします

  • Content typeはapplication/json
  • Secretは空
  • 「Just the push event」にチェック
  • Activeにチェック

この状態で「Add webhook」ボタンをクリックします。

Griflet上でビルドを試験する

デプロイキーとWebhookの設定が終了したら、基本的な設定は完了です。

Grifletのプロジェクト作成成功画面の「プロジェクトのメイン画面へ移動」をクリックします。

「まだドキュメントビルドは行われていません」と表示されているはずです。 もしここですぐにビルド結果を見たい場合には「ビルドをリクエストする」ボタンを押します。

GitHub上でWebHook設定が正しくされている場合、このボタンを押さなくても、以降レポジトリへのコミットが行われた段階でビルドリクエストは発行されます。少し高度な話ですが参考まで、GitHubが最初に発行するWebHookの「ping」は無視されます。

ビルド結果を確認する

少し待ってからページを再読み込みしてください。GitHubプロジェクトからRe:VIEWのデータを取得し、PDFのビルドが始まっている様子が表示されるはずです。

今回の例ではreview-initで作られた標準テンプレートをそのままビルドしたので、表紙や内容も含めて標準テンプレートそのままのPDFが出てくるでしょう。画面上の「pdf(4p)」というリンクからPDFをダウンロードできます。

以降、GitHub側の原稿を更新するたびに(Webhookの仕組みにより)勝手に新しいバージョンのPDFが生成されるか、ビルドエラーが発生すればその旨表示されるようになります。

仕組み上、「ビルドをリクエストする」ボタンをこれ以降押すことはめったにないでしょう。なお、ビルド失敗したときに、このボタンを押しても再度ビルドを試してくれたりはしません。

ビルド結果の詳細を見る

前掲の図の画面左側に「5f58b9」という文字列のリンクがあります。このリンクをクリックすると、そのコミットにおけるビルド結果(標準出力と標準エラー出力)、ソースとなった.reファイル等を見ることが出来ます。

ビルド失敗時には、この画面の、特に標準出力(今回は「pdf-stdout」)や標準エラー出力(今回は「pdf-stderr」)を確認すると、どのステップで失敗したかが分かるかもしれません。

Grifletのバグという可能性もありますので、原因がわからない場合には気軽にお問い合わせください。

ビルド設定の仕方

標準では、Grifletは各プロジェクトのRe:VIEWソースに対してreview-pdfmaker config.ymlを実行することで、PDFを生成します。 また、PDFにはIPAフォントが自動的に埋め込まれます。

.griflet.ymlというYAML形式のファイルをRe:VIEWのプロジェクトへ含めることでこの挙動を修正し、標準の挙動を上書きすることが出来ます。
併せて、epub, html形式等、Re:VIEWが対応する別フォーマットのデータをビルドするよう指定することも出来ます。

シンプルな例を示します。この例ではpdf (IPAフォント埋め込み), epub, htmlを生成するようになります。

ビルド失敗時には、この画面の、特に標準出力(今回は「pdf-stdout」)や標準エラー出力(今回は「pdf-stderr」)を確認すると、どのステップで失敗したかが分かることがあります。

specs: pdf, epub, html

この項目は現在準備中です。しばらくお待ちください。