このエントリーをはてなブックマークに追加

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

Sphinx アドベントカレンダー 2012の14日目です。

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の書き方

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

  • 条件式

    • not
    • and
  • タグ

    • makeで指定したbuilder名
    • コマンドオプションで-tで指定
    • conf.pyで指定

例えば、

.. only:: html and draft

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

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

AutoImage拡張

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

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

AutoImage 拡張

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

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

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

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

まとめ

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

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

参考

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