あなたの知らない toctree の世界

numfig を実装してやらぁ！と息巻いてコードを書き始めたところ、
シンプルだと思っていた toctree の裏に思わぬ魔境が広がっていて
思わず部屋の隅っこで震えてしまった @tk0miya です。

Sphinx のリファレンスを舐めるように読み尽くした toctree マニアには常識かもしれませんが、
さっと読み飛ばした人々には toctree は謎機能の山に見えてくるはずです。

URL が指定できる

リファレンスの一節にそっとこんなことが書かれています。

また、ドキュメント名の代わりに、HTTPのURLを指定することで外部へのリンクを追加することもできます。

toctree って他の reST ファイルをリンクするためにだけあるんじゃなかったんですね。
早速使ってみましょう。

.. toctree::

   http://www.google.co.jp/

そしてこれをビルドしてみるとこんなふうになります。

どうやら URL を指定するとリンクテキストが None になってしまうようです。
この動作についてリファレンスには説明がありませんが、
toctree にはタイトルを付ける記法があるのでそれで回避するとよいでしょう。

.. toctree::

   Google <http://www.google.co.jp/>

いまいち使い所がつかめていないのですが、
目次に URL を入れたくなったときに使ってみてください。

ちなみに LaTeX の目次には効果がありません。

:numbered: オプションが引数を取るようになった

Sphinx 1.1 から numbered オプションが引数を取るようになっています。

特定の深さまでのナンバリングだけを行うこともできます。
numbered 引数に対して、数値で深さを指定してください。

というわけで、このオプションを指定してみます。
まず深さを指定しない場合の例。

続いて :numbered: 2 を指定した場合。

そして :numbered: 1 を指定した場合。

番号を振る階層が変化していますね。

なお、このオプションは LaTeX 経由で PDF を出力した場合は効力がありません。
そもそも LaTeX 経由ででは :numbered: 指定なしでも章番号が割り振られますし、
他のフォーマットでは :numbered: の指定は効果がないので、
HTML 専用オプションとして割り切って考えるのが良さそうです。

謎の self 指定

リファレンスを読み進めていくと、こんな記述もあります。

self は特別なエントリー名として扱われます。toctreeディレクティブを含むドキュメント自身を表します。これは、toctreeを使用して、”サイトマップ”を作成したい場合に便利です。

どうやら self という文字列を toctree に指定することができるようです。
試してみましょう。先ほどのドキュメントに加筆してみます。

.. toctree::
   :numbered:

   sub
   self

するとこんな出力になります。

何に使えるのか、いまいちよくわかりませんね。

ちなみに、self という名前は予約されているので self.rst というファイルを作っても
toctree で指定することはできません。ご注意ください。
subdir/self は問題ないので、self.rst を作れと遺言を受け取った方はディレクトリを掘るとよいでしょう。

toctree で循環参照をすると warning で注意される

toctree は名前の通りツリー構造を期待しているので、循環参照が起きることは想定していません。そのため、循環参照が起きるような指定をすると warning が出てきます。

例えば、自分自身のファイル名を指定すると…

.. toctree::

   index

こんなふうに注意されます。

/Users/tkomiya/work/tmp/foo/index.rst:: WARNING: circular toctree references detected, ignoring: index <- index

複数のファイルをまたがって参照しても注意されます。
次の例は index -> sub -> subsub1 -> index という循環がある場合の warning です。

/Users/tkomiya/work/tmp/foo/sub.rst:: WARNING: circular toctree references detected, ignoring: sub <- index <- subsub1 <- sub
/Users/tkomiya/work/tmp/foo/subsub1.rst:: WARNING: circular toctree references detected, ignoring: subsub1 <- sub <- index <- subsub1
/Users/tkomiya/work/tmp/foo/index.rst:: WARNING: circular toctree references detected, ignoring: index <- subsub1 <- sub <- index

なお、循環参照と :numbered: オプションを組み合わせると Sphinx ごと死ぬというバグを見つけたので、
循環参照マニアの人はこのバグが直るのを待つと良さそうです。

また、toctree はツリーにせよ、というコンセプトを無視して、
複数のファイルに特定のファイルをつなげて、ひし形に toctree を組むこともできます。
そうすると、navigation link が壊れたり*1、:numbered: による採番が狂ったりします。

まとめ

toctree は徐々に機能が追加されてきているものの、何に使うのかよくわからないものもあり、
アンバランスかつバギーな状態のようです。

せっかくですのでバグハンターの方々は、この辺りで楽しまれると良いのではないでしょうか。

あ、循環参照してる文書で make latex したら死んだ。
終わる。

*1:次へ、前への繰り返しで文書を辿れなくなる