numfig の闇と向き合う
前の記事で
あとは numfig の応用で自動採番をすることもできるようになるでしょう。
なんてことを書いてみたのだけど、よく考えてみると一度も numfig を使ったことがなかったので
これを機に挑戦してみんとてするなり。
numfig をインストールする
numfig はパッケージングされておらず、ファイルひとつだけぽつんとリポジトリに置いてあります。
pip などは使えませんが、curl で落としてきて、load path を書き換えてあげれば
Sphinx 拡張として読み込むことができます。
$ cd /path/to/doc $ curl -LO https://bitbucket.org/arjones6/sphinx-numfig/raw/b2345f7d9fabefbd103c31cc0c4c26c68b29ac6a/numfig.py $ vi conf.py import os import sys sys.path.insert(0, os.path.dirname(__file__)) extensions += ['numfig']
numfig は拡張をインストールしておけば、figure ディレクティブを書くだけで自動的に番号を振ってくれます。
.. figure:: logo.jpg this is caption
また、ラベルを付けておくと :num: や :page: などのロールを使って、
図の番号を取得したり、該当ページへとリンクを張ったりすることができます。
numfig の闇
さて、ここまでは順調ですが、使ってみると気になるところがいくつも出てきます。
- HTML 形式のサポートが適当
- :page: はスキップされてしまいリンクが作成されない
- そもそも :num: を使うと HTML に変換できない
- 自動採番の範囲がページ単位 (別の rst ファイルに移動すると 1番から)
- figure だけしか扱うことができない
- ラベルにアンダースコアを使うとリンク切れになる
- :num: も :page: も別の章の figure が対象だとリンクできない
- 同じ章の中なら問題なし
- tex のソースを読むとラベル名に \label{chapter2:hello-world} と chapter 番号がついてるので… orz
ちょっと使っただけでこんな感じで文句が出てくるわけですが、
調べていくとどうやらこの numfig 、作りっぱなしで放置されているもののようです。
おそらく作者は TeX で論文を書いたところで満足してしまったんじゃないでしょうか。
その他の numfig 実装
fork 先を覗いていくと、いくつか numfig のバグを直したものが見つかります。
しかし、調べていくとかすかな希望が絶望に変わります。
- https://bitbucket.org/keik/sphinx-numref
- table も扱えるようにしたもの。
- HTML で :num: が使えない問題は治っているものの、rst ファイルをまたぐと落ちる
- https://bitbucket.org/takaakiaoki/sphinx-numfig
- こちらも table に対応したもの
- HTML で :num: は使えないまま
- sphinxtr
- Sphinx で論文を書くための拡張群的な位置付け
- table や subfigure (独自形式) に対する自動採番に対応
- 大きく書き換えられているが、やはり HTML ではコケた orz
- 別の章だとリンクできないのは相変わらず
autonumber を試す。
numfig が気になってるとつぶやいたところ、@shimizukawa から autonumber.py を紹介されました。
@tk0miya このへん https://t.co/WfUYx3tJbH にあるURL https://t.co/vYsAYg4fIv のコード。アイディアはよさそう
— Takayuki Shimizukawa (@shimizukawa) 2014, 7月 26
autonumber.py は sphinx-dev group で名乗りを上げた numfig 界の新星という位置付けっぽい。
インストールは numfig と同様です。
$ curl -LO https://raw.githubusercontent.com/SimTk/openmm/master/docs/sphinx/autonumber.py $ vi conf.py import os import sys sys.path.insert(0, os.path.dirname(__file__)) extensions += ['autonumber']
使い方は numfig と少々異なり、caption の一部として :autonumber: ロールを使うようです。
.. figure:: logo.jpg :autonumber:`Figure, hello` caption
- autonumber
- ロールの前半(カンマの前まで)が図番号の prefix になります。
(この例だと Figure 1-1 と番号がつく)
また、図番号を取得する際は :numref: を使います。
:numref:`Figure, hello`
参照する際は :autonumber: ロールと同じものを使います。
autonumber.py の印象 (というかダメ出し)
- ロールで実装されているので、場所を選ばない
- table でも他のものでも地の文でも使える
- README がないので使い方がわかりづらい
- toctree に :numbered: オプションを渡さないと落ちる
- rst ファイルをまたがると参照できない
- Sphinx/docutils のリンクの仕組み(ラベル)をまったく使っていない
- 図表番号はとれるが、リンクを作ることはできない
- 書きづらい上に、いちいち :autonumber: を書かないと採番されない
つらい。
まとめ
今日現在、まともな numfig の実装なんてなかったんや… orz