gistfile1.txt

まだお酒が残っているので gist に下書き。そのうち昇華してブログにでもするのではないだろうか。

技術書典7 で『Inside Sphinx』を頒布しているとき、お客さんから質問をひとつもらった。
質問の内容は極めてシンプルで、「本文中のある要素をクリックするごとに表示/非表示を切り替えるにはどうするとよいか」というものであった。
その場ではいいアイディアが出てこなかったため、CSS + JS で解決するとよいのではと答えたのだけど、
よくよく考えてみるとこれは HTML5 で導入された `<details>` タグの挙動そのものなのであった。

さて、期待されるアウトプットが整理できたところで、この課題を解決するにはどういうアプローチがよいだろうか。
ぱっと思い浮かぶ選択肢はいくつかある。どういうものが思いつくだろうか。そして、どれを選ぶべきだろう。

その中で僕が選択して実装したものがこれだ。
https://gist.github.com/tk0miya/e65332b02b57a801638cb1ea4198a6fb
実装自体は店番の合間に書いたもので、1時間ぐらいで書き上げている。行数もほんの 70行ぐらいだ。
同じ時間で書き上げられるかはともかく、知識としては『Inside Sphinx』で扱っている範囲のものである。

おそらく、ここが僕が本書(の完全版)に込めるべきものではないかと考える。
どうしてこのアプローチを選択したのか、もしくは他のアプローチを選択しなかったのか。
そこには僕なりの考えによる取捨選択が行われており、その考え方や観点こそが人に伝えるのが難しい経験の結晶だと気づいたのだ。

『Inside Sphinx』はボトムアップのアプローチで、テクニックをひとつずつ積み上げるように説明をしている。
ディレクティブとはこう作る、カスタムノードとはこう作る、Transform はこう使う、などなど。
それは Sphinx 拡張を作るために必要な知識であることには間違いないのだが、これを積み重ねただけでは拡張は作れないことに気づいたのであった。
これは次のアップデートに向けての自分への課題としたい。お酒も入ってるし。

なお、せっかく作ったからとパッケージにしたのがこちら。テストコードも書いたのでそれなりに動くはずだ。
https://pypi.org/project/sphinxcontrib-details-directive/