技術書典5 で『マスタリング docutils』を出版しました

先週末、技術書典5に「マークアップ言語愛好会」というサークルで参加し、『マスタリング docutils』という本を出版しました。
techbookfest.org
techbookfest.org

マスタリング docutils

この本はこんなまえがきからはじまります。

みなさんは docutils をご存知でしょうか。
docutils はふたつの側面を持つソフトウェアです。
ひとつは Python 製のドキュメント処理フレームワークとしての側面。
もうひとつはそのフレームワークの上に実装されたドキュメント変換ツール群としての側面です。


本書では、前者のドキュメント処理フレームワークとしての docutils にスポットを当て、どのような構造をしているのか、
どのような順序で処理が行われるのか、そしてどのように拡張するのかについて紹介します。

Sphinx はこの docutils の上に構築されたツールです。したがって、Sphinx や Sphinx 拡張を作る上で避けては通れません。しかし、残念なことに docutils はドキュメントや解説が少なく、理解がとてもむずかしいという問題があります。
自分が Sphinx の拡張を書き始めたときに、最初につまづいた (そして今も時々つまづく) のがここです。

本書はその問題をカバーすべく、docutils がどのような構造をしているのか、どのようなフローで処理が進むのか、
そしてどこが拡張ポイントなのかというのを紹介したおそらく世界初の docutils 解説書です。

執筆から販売まで

申し込んだ時点から予想はしていたのですが、今回は執筆時間に充てる時間が限られていました。
9月半ばに開催された PyCon JP 2018 での発表資料づくりに手間取ってしまったため、執筆できるようになったのが 2週間前でした。
そこからハイペースに執筆をして仕上げたのが本書です。

執筆期間が短いとボリュームが…という懸念があったものの書き上げてみると 60ページ弱になりましたし、
肝心のクオリティについても、(断腸の思いで一部見送った章があるものの) おおよそまんぞく行くものができました。

普段からよく触って中も覗いている docutils ですが、今回の執筆にあたって改めてこんなことをしています。

  • 歴史を追うために Doc-SIG の投稿を(ピックアップしながら)斜め読みした
  • 経緯を知るために PEP 256-258 をひたすら読んだ
  • 説明のために docutils のコードを読みふけった

ですので、内容についても胸を張ってお見せできるものです。

ひとつ残念だったのは、ギリギリすぎるスケジュールによって印刷に回す時間が取れなかったことですね。
そもそも技術書典に申し込んだゴールのひとつが Sphinx を使って、執筆から出版(印刷)までの過程を体感してみるというものだったので、自分の目標としては未達成でした。残念。

ツール

今回執筆に使ったのはこのあたりのツール / サービスです。

  • Sphinx (執筆、出力)
  • gitlab (CI)
  • Google drawings (画像)
  • slack (オンラインレビュー / 監視)
  • ラクスル (ダウンロードカード印刷)
  • ジョナサン (セルフ缶詰スペース)

反省

Twitter でいろいろ書いたのを貼り付けておきます。









今後の予定

本書をほしいという奇特な方が現れたので、Booth でダウンロード販売をしています。
興味がある方はこちらからどうぞ。

また、ダウンロードカードはまだ余っているので、カードが欲しい人はお声がけください。

大事なこと

本書で docutils に興味を持った人は、実際に docutils フレームワークをフル活用している事例として Sphinx があるので、
ぜひとも一緒に開発しませんか！
Sphinx プロジェクトではいつでも協力者を求めていますよ！