読者です 読者をやめる 読者になる 読者になる

once upon a time,

Iris Tradをビール片手に聞くのが好きなエンジニアが、機械学習やRubyにまつわる話を書きます

Docker imageを用意してWindows/macOSでスムーズに同人誌を作った話(Sphinx編)

こんにちは、ハイラルに移住したchezouです。最近は、Rから始まりRで終わる言語をよく書いています。

いよいよ明日に迫ってきた技術書典2ですが、お-13で技術書供養寺として頒布を行います。 内容は、僕の機械学習の実務におけるtipsとfastFMを使った推薦、@tokorotenさんのKickstarterの分析、@hagino3000さんのスプラトゥーンデータマイニングということで盛り沢山です。初めての同人誌ですが、140ページを超えた薄くない薄い本になりました。

是非買いに来てください!

tl;dr

  • 技術書を書くときに、LaTeXを含んだDocker image使ってCIでビルド出来るようにすると共同執筆が捗るよ

前回までのあらすじ

今回は、メンバーがWindowsの人とmacOSの人の混成チームであったこと、全員がPythonに馴染み深い人だったので、reStructuredTextベースのSphinxで書きました。

なお、メンバーの中には一度Jupyter notebookで下書きを書いて、それをnbconvertを使ってrstとして変換する人もいました(賢い)。この辺、Jupyterは元々Pythonのエコシステムなので数式含んだJupyter notebookをrstまで変換できるなら、良い選択肢かもしれません。

SphinxのDocker imageの作り方等は過去に書いているのでそちらを参考にしてください。

chezou.hatenablog.com

なぜDocker imageを用意したか?

  • 原稿執筆は余計な障害(環境構築とか)が入ると、その対応で燃え尽きる
  • 原稿執筆は往々にして〆切ギリギリから開始するので、最短距離を走れるようにしたほうが成功確率が上がる
  • OSが異なる環境でのLaTeX周りのトラブルシュートをしたくなかった
  • ビルドにコケる原稿のpushが防げた

この目論見はすべて当たりました。実際に、共著者の皆様からはすぐに執筆開始できたとの喜びの声をいただきました。

[追記]

じつはどちらもLinuxで書いていたともいえることがわかりました…

[/追記]

Sphinxのdocker imageでできたこと

  • WindowsでもmacOSでもすぐに書き始められる状況を準備できた
  • Gitlab CIを使って、マージされたものをCIでPDFを用意する
  • 奥付を作る
  • (docker image関係ないけど)re:viewで書きかけていた原稿をreSTに変換できた

奥付については、少しトリッキーなので後述します。

Sphinxのdocker imageでできなかったこと

  • 原稿のグレースケール化(Adobe Acrobatでやった)
  • 納得の行くfontの埋め込み(ヒラギノを使うためにmacOSでフォントを埋め込んだ)

Previewのグレースケール化は信用ならないので、グレースケール化には少なくともmacOSだとAcrobatが必須かもしれません。

fontの埋め込みは、IPA系のフォントだとライセンス的に問題なくコンテナ内で埋め込めるのですが、日本語の太字が綺麗にでなかったので結局MacSphinxをビルドしてヒラギノを埋め込みました。*1 そのおかげで、tokorotenさんの原稿の画像サイズが少しずれて手直しが入りました。。。dockerベースでフォント埋め込みまでやっていればいけたのに…。無念。

奥付の作り方

以外とハマったんですが、以下のgistのように一度citationをflashすれば行けます。 デフォルトでは、citationが必ず最後に来るようになっていますが、それを回避できます

Sphinxで奥付を足す方法 · GitHub

Re:VIEWの書きかけの原稿をreSTに変換できた(相互変換出来る時代に)

実は書きはじめのときに、shirouさんがRe:VIEWの原稿をSphinxの原稿に変換していただきました。ありがとうございました。

github.com

何故か手元にあった結構ボリュームのあるRe:VIEWの原稿を変換できて、大体の問題は解決されているのではないかなと思います。

なお、逆向きのSphinxの原稿からRe:VIEWを出力するプラグインもあります。これで、気が変わって別のフォーマットにexport/importが容易になりましたね!

github.com

おわりに

今回は、shirouさん、shibukawaさん、tk0miyaさんといった#sphinxjpの皆様にお世話になりました。困ったことがあったときに、日本語で聞ける環境があるというのは非常に助かりました。

それでは、明日は秋葉原UDX2階のアキバ・スクエアで僕と握手!