コード片(code-block)にキャプションをつける

rstのファイルでリストに通し番号を入れる(久々にシェル芸) を見て、"code-block にキャプション付けられなかったっけ?" とおもって調べてみたところ、
Sphinx の code-block ディレクティブも docutils の code ディレクティブもどちらもキャプションをサポートしていませんでした。

僕らが普段目にする雑誌では、コード片にはそれぞれ「リスト 1. 〜〜〜」のようなキャプションがついています。
それと同様の記述は Sphinx ではできないのでしょうか。

よろしい、ならば拡張だ

標準のディレクティブを書き換えるのは気が進まない*1のですが、目的のためならば手段は選んでいられません。
早速 code-block ディレクティブを書き換えることにしましょう。

ということで、書き換え終わったものがこちらです。

code-block ディレクティブに :caption: オプションを加えたものです。

HTML では次のように出力されます。
f:id:tk0miya:20140726020048p:plain

また、PDF では次のように出力されます。
f:id:tk0miya:20140726020108p:plain

まとめ

adhoc なやりかたですが、code-block ディレクティブに :caption: オプションを付けることができました。
あとは numfig の応用で自動採番をすることもできるようになるでしょう。

問題はこの機能は標準ではないということなので、興味がある人は本家にプッシュしてみてください。

*1:標準の reST のように見えて、標準ではない動きをするものというのは非常に気味の悪いものです。