Sphinxで出力フォーマットごとに記述を変更する¶

Sphinxは一つのrstファイルからhtmlやepubなどいろいろな形式で出力することが出来ます。出力形式の差はSphinxが吸収してくれるため、普段は処理を意識する必要はなく単に make html と叩くだけなのがありがたいところです。

しかし、どうしても個々の出力先フォーマットに応じた処理を書きたくなる場合があります。特に顕著なのが画像の大きさで、htmlとlatexでは画像の大きさが倍違うことがあります。

そんなときに使えるのが only directiveです。

onlyの例¶

only directiveの例を記します。

.. only:: not latex

   .. image:: figs/notation3.png
      :scale: 40

.. only:: latex

   .. image:: figs/notation3.png
      :scale: 80

こう書くと、latexの場合はscale 80で、それ以外の場合はscale 40で画像が表示されることになります。

onlyに続く文字、上の例では not latex などですが、これは実は条件式です。ここには条件式とタグを記載できます。それぞれ使える内容は次の通りです。

例えば、

.. only:: html and draft

の場合、html builderを使い、かつ、 -t draft と指定した場合にのみ出力されます。

詳しくは only directive を参照してください。

onlyを使えば出力フォーマットごとに設定を変更できます。しかし、ほぼ同じ内容を二回書くのは手間ですよね。

ということで、Imageだけですが、builderごとにオプションを切り替えられる拡張があります。

これを使えば、以下のように簡単に記述できます。

.. autoimage:: notation3.png
   :scale-html: 40
   :scale-latex: 80

なお、 make html で実行するとこのオプションはキャッシュされてしまい、次に例えば make latex と実行してもhtmlの場合のオプションが使われてしまいます。

これを回避するためには sphinx-build に -E オプションをつけるとキャッシュを使わなくなります。

出力先あるいは任意のタグで記述を変更できる only directive について紹介しました。また、AutoImage拡張を紹介しました。

Sphinxが出力フォーマットの面倒をすべて見てくれれば良いのですが、現実的には出力フォーマットに依存する処理は結構多いです。(特にLaTeX)そういうときにこのonly directiveを使うと適切な場合分けができるのではないかと思います。

この記事はこちらを参考にしました。ていうか一部をそのまんま取り出しただけです。すいません。