オライリーへの入稿用の Sphinx拡張、sphinxcontrib-getstart-sphinx をリリースしました。

いつぞやの記事で「Sphinx をはじめよう 第2版」を書いた話をしたのを覚えてらっしゃいますか?ちなみに、オライリーさんのページはこちらです。以前に紹介したときは、紙媒体はイベントなどのオフラインでの購入に限定されていたのですが、いまでは通販でも手に入るようです。
電子書籍も好評発売中ですので、興味がある方はぜひとも見ていただければ、と思います。
www.oreilly.co.jp

さて、宣伝から話を戻しましょうか。
オライリーマニアのみなさんに於かれましては、オライリー・ジャパンさんの電子書籍の制作に Re:VIEW が深く関わっているのは既にご存知かと思います(参考:Community Blog - オライリー・ジャパンのePUBフォーマットを支える制作システム)。

この本の出版の際も、Sphinx で書かれた原稿を Re:VIEW に変更し、レビューや校正の段階では Re:VIEW 原稿を修正するというステップを踏んでいました。Sphinx をメンテしていて、reStructuredText に慣れ親しんだ身としては、ちょっと残念な気分でした。

Re:VIEW 記法に慣れていないというのもありますし、来るべき(?)第3版のために、reSTの元原稿も同時に変更していたというのもあり、Re:VIEW で原稿をいじるというのがちょっと負担だったのは確かです。reviewbuilder などによって、こうしたインピーダンスミスマッチは減ってきているとはいえ、いまだに乗り越えなくてはならない壁が残っていたのが、この書籍の制作過程でした。

さて、ここで黙っていたら男がすたるってもんですよね。Sphinx 拡張メイカー (自称)の名にかけて、こういう問題は拡張のちからでねじ伏せなくてはなりません。
というわけで、いつものごとく Sphinx 拡張を作りました*1。それが sphinxcontrib-getstart-sphinx です。

この拡張は、README に

sphinxcontrib-getstart-sphinx is a collection of Sphinx extensions to build Sphinxをはじめよう 第2版 (Getting Started with Sphinx 2nd Edition).

とあるように、Sphinx をはじめよう 第2版 のビルド用に作られた拡張群です。当初は sphinxcontrib-oreillyjapan にしようかと思ったのですが、流石にネームスペースが強すぎたので自重しました。

このパッケージには以下の拡張が含まれています。

  • better_docref
    • :doc: による参照を書籍向けのいい感じにする
    • 具体的には『第1章「Sphinxとは」では…』のように章番号を付けた参照に置き換える
  • column
    • コラムを書くための column ディレクティブを追加する
    • もちろん Re:VIEW への変換にも対応している
  • footnote_relocator
    • 脚注を各パートの末尾に移動する
    • 標準の Sphinx では章や節の途中に脚注を置くので、EPUB など向けに出力を調整する拡張
  • glossary_decorator
    • glossary の用語部分を太字にする。これでキミのドキュメントもオライリー風だ!
  • oreilly_review_table
    • オライリーさんの内部ツールに合わせて Re:VIEW 出力形式をごにょごにょする

getstart_sphinx 拡張はアラカルト形式ですので、この中の任意のものを有効にすることもできます (もちろん全部有効にしてもオッケー)。

というわけで


というのが一歩進んだわけです。

Sphinx をはじめよう 第2版 ともどもよろしくお願いします。

*1:書き上げたまでは良かったものの、最近まで放置していたので、なんというか、ごめんなさい