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 だけしか扱うことができない
    • sphinx.ext.graphviz で図を作ってもスルー (1.2 から caption が指定できるのに…)
    • table なんてもってのほか
  • ラベルにアンダースコアを使うとリンク切れになる
  • :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 を紹介されました。

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