ちょっと話題の記事

[自動化]GitHubで管理しているドキュメントをGitBookでPDF化し、Backlogの共有フォルダにアップロードする

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

モバイルアプリサービス部の五十嵐です。

私が担当するプロジェクトでは、GitHubでドキュメントを管理し、それをGitBookでPDFファイルにしてお客様へ提供しています。GitBookを使ってGitHubのドキュメントをPDFにする方法は、以前、藤村が紹介しました。

GitBook 環境を準備してみる | Developers.IO

私もこの方法で何度かPDFファイルを作っていたのですが、環境準備さえしてしまえば数コマンド打つだけ・・・とはいえ数コマンドを覚えておくのも面倒ですしゴミファイルを消したりとか色々やることがあります。そこで、この一連の操作をスクリプト化しました。また、PDFファイルはBacklogの共有ファイルにてお客様へ提供しているので、その作業も合わせてスクリプト化しました。

スクリプトは、将来的にはGitHubのMerge PRイベントをトリガーにJenkinsなどで動かすことを想定し、シェルスクリプトで書いています。とりあえず今回はそこまで行ってないので、ローカル環境で手動実行するまでです。

GitHubで管理しているドキュメントをGitBookでPDF化

GitBookのコマンドツールのインストールが完了しているものとします。 以下のスクリプトを保存し、実行権限を付与します。

gitbook.sh

やっていることはコメントとコマンドに書いてある通りなので説明は不要かと思います。

Backlogの共有フォルダにアップロードする

実はこちらの方が少し苦戦しました。BacklogにAPIが提供されているのは知っていたので、その中にファイルアップロードもあるだろうと考えていたのですが、ありませんでした。で、もう少し調べたところ、Backlogの共有ファイルは、実はWebDAVに対応していることが分かりました。

Windows 7 の設定 | Backlogを使いこなそう | Backlog [バックログ]

これを使って、MacにWebDAVの共有フォルダをマウントして、ファイルコピーすることにしたのが以下のスクリプトです。

backlog_upload.sh

これも見ての通りですね。WebDAVの認証情報はキーチェーンで保存されているものを使っているので、実行時に以下のダイアログが表示されます。「常に許可」を選択してしまえば初回だけです。

スクリーンショット 2016-02-13 3.12.46

Jenkins(Linux)に移植するときは、認証情報は /etc/davfs2/secrets とかに保存しておけば良いのかな?今度試してみます。

ひとつ小さな気づきですが、WebDAVファイルサーバにcpコマンドでファイルをコピーした時、ファイルは正常にコピーされるのですが、次のエラーが出力されました。

cp: SPEC.pdf: could not copy extended attributes to /Volumes/XXXX/...: Operation not permitted

調べたところ、以下のリンクに答えが書いてありました。

What isn't copied when Mac OS X's cp complains "extended attributes not copied"? - Quora

ファイルシステムの違いで、Macのファイルシステムが持つメタ情報がWebDAVファイルサーバでは欠けてしまうということの警告らしいです。今回は影響ないですが、そういうこともあるんだ、という発見でした。

次のステップ

ドキュメントに不可欠なのが「変更履歴」ですね。GitHubで管理しているのだからIssueやPRをまとめれば良いだけのはず。でも手動でやるのは手間がかかる。ということで探したらあるっぽいので、これを含めて自動化するというQiitaの記事を所望したら私が書くことになったので次はこれにチャレンジしてみようと思います。

スクリーンショット 2016-02-13 2.02.39