Sphinxにおける数式のサポート

バージョン 0.5 で追加.

HTMLでは、ネイティブでは数式の記法はサポートされていません。Sphinxでは、ドキュメントの中に数式を表現するための拡張機能をいくつかサポートしています。

基礎的な数式サポートは、 sphinx.ext.mathbase に含まれています。他に数式をサポートを行うための拡張機能を作成する場合には、使用できるのであれば、このモジュールを再利用してください。

注釈

mathbaseextensions の設定値に追加しないでください。追加するのは代わりに、これから説明を行う sphinx.ext.imgmath もしくは sphinx.ext.mathjax を設定してください。

数式の入力言語としてはLaTeXのマークアップを利用します。これはプレーンテキストで数式を表現する記法としてはデファクトスタンダードになっています。また、LaTeX出力を行う場合には、変換をしないでそのまま利用できるというメリットもあります。

autodoc で読み込まれた Python docstrings の中に数式を入れるときには、すべてのバックスラッシュを二重にするか、Pythonのraw strings (r"raw") を使う必要があることに注意してください。

mathbase では以下の値が設定できます:

math_number_all

もし表示されるすべての数式に番号を振りたい場合、このオプションを True にします。デフォルトでは False です。

mathbase は以下の新しいマークアップの要素を定義しています:

:math:

インラインの数式のロールです。以下のようにして使用します:

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
.. math::

数式を表示するディレクティブです。この数式は1行丸ごと使って表示されます。

このディレクティブは、複数行の等式をサポートしています。複数行に記述したい場合には、空行で区切ります:

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

それぞれの数式は 分割された 環境にセットされます。もしも、複数行の等式をきれいに整列させたい場合には、 \\ で区切って、 & 記号を使って整列させます:

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

もっと詳しく知りたい場合には AmSMath LaTeX パッケージ のドキュメントを参照してください。

数式が一行のテキストに収まる場合には、ディレクティブの引数として記述もできます:

.. math:: (a + b)^2 = a^2 + 2ab + b^2

通常は数式には番号は付きません。もしも数式に対して番号をつけたくなった場合には、 label オプションを使用してください。これが指定されると、数式のラベルを選択できます。この数式のラベルを使ってクロスリファレンスを作成できます。サンプルを見る場合には eqref を参照してください。ナンバリングの形式は出力フォーマットに依存します。

nowrap オプションを使用することで、math環境で自動的にラッピングされるのを止めることができます。このオプションを指定した場合には、自分自身で適切な設定を行う必要があります。 サンプル:

.. math::
   :nowrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}
:eq:

数式のラベルに対する、クロスリファレンスを行うためのロールです。この機能は、現在では同じドキュメント内でのみ動作します。 サンプル:

.. math:: e^{i\pi} + 1 = 0
   :label: euler

Euler's identity, equation :eq:`euler`, was elected one of the most
beautiful mathematical formulas.

sphinx.ext.imgmath – 数式を画像にレンダリングします

バージョン 1.4 で追加.

この拡張機能は LaTeX と dvipng または dvisvg を用い、数式を PNG または SVG 画像に変換します。当然ながら文書をビルドするコンピュータではこれらのプログラムが動作する必要があります。

この拡張用の設定値がいくつかあります。これらの設定値を変更することで、画像のビルドをカスタマイズしたりできます:

imgmath_image_format

出力する画像のフォーマット。デフォルトは 'png' です。 'png' または 'svg' のいずれかの値をとります。

imgmath_latex

LaTeXを呼び出す場合のコマンド名です。デフォルトでは 'latex' となります。もしも latex コマンドが実行ファイルの検索パスにない場合には、フルパスを指定する必要があります。

この設定はシステム間で共通にはできないため、conf.py の中で設定することは通常行いません。むしろ、次のように sphinx-build コマンドの -D オプションとして与えるほうが望ましいでしょう。

sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html

この値にはLaTeXの実行ファイルのパスだけを含むようにして下さい。LaTeXに追加で渡したい引数は、こちらに入れないで、 imgmath_latex_args を使用してください。

imgmath_dvipng

dvipng を呼び出す時のコマンド名です。デフォルト値は 'dvipng' です。もしも dvipng が実行ファイルの検索パス外にある場合には、絶対パスを指定してください。このオプションは``imgmath_image_format`` が 'png' の場合にのみ有効です。

imgmath_dvisvgm

dvisvgm を呼び出す時のコマンド名です。デフォルト値は 'dvisvgm' です。もしも dvisvgm が実行ファイルの検索パス外にある場合には、絶対パスを指定してください。このオプションは``imgmath_image_format`` が 'svg' の場合にのみ有効です。

imgmath_latex_args

LaTeXに渡す追加の引数です。リストで渡します。デフォルト値は空のリストになります。

imgmath_latex_preamble

数式のコード片を変換するのに使用する、短いLaTeXファイルの中の前置きとして入れる、追加のLaTeXコードです。デフォルトでは空です。このオプションは、例えば、数式の中で使いたいコマンドのためのパッケージを追加するのに使えます。

imgmath_dvipng_args

dvipngに与える、追加の引数をリストで渡します。デフォルト値は ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'] で、画像をデフォルトよりも、多少暗く、サイズは少々大きく、背景を透過にしたPNGを生成します。このオプションは``imgmath_image_format`` が 'png' の場合にのみ有効です。

imgmath_dvisvgm_args

dvisvgmに与える、追加の引数をリストで渡します。デフォルト値は ['--no-fonts'] です。このオプションは``imgmath_image_format`` が 'svg' の場合にのみ有効です。

imgmath_use_preview

dvipng は、レンダリングされたテキストの”深さ”を決定できます。例えば、行の文章の中に分数を写植する場合、テキストのベースラインと、生成された画像の底辺の高さが同じであってはならず、画像はベースラインよりも少し低い位置になるべでしょう。これがTeXの世界でいう”深さ”です。もしもこのオプションが有効になっていると、ベースラインからの正しいオフセット量の 垂直揃え のスタイルで画像が生成され、HTMLドキュメントに入れられます。

残念ながら、このオプションは、 preview-latex package がインストールされていなければ動作しません。そのため、デフォルトの値は False になっています。

現在このオプションは``imgmath_image_format`` が 'png' の場合にのみ有効です。

imgmath_add_tooltips

デフォルトは True 。Falseの時は、画像の”alt”属性に、LaTeXのコードを埋め込みません。

imgmath_font_size

表示する数式のフォントサイズです(単位は pt)。デフォルト値は 12 です。この値は正の整数値でなければなりません。

sphinx.ext.mathjax – JavaScriptを使った数式のレンダリング

バージョン 1.1 で追加.

この拡張機能は、HTMLの中に数式を埋め込みます。JavaScriptの MathJax パッケージは、ブラウザの中で、LaTeXのマークアップを読める数式に、動的に変換します。

MathJax(と必要なフォント)はとても大きいため、これはSphinxには組み込まれていません。

mathjax_path

HTMLにJSMathをロードして読み込ませるための、JavaScriptファイルへのパスを設定します。

デフォルトは http:// で始まる MathJax CDN から取得するJSのURLです。もし、オフラインでMathJaxを使いたい場合、MathJaxをダウンロードしてこの値を違うパスに変更してください。

パスは、絶対パスでも相対パスでも指定ができます。相対パスの場合、ビルドした出力の _static ディレクトリへのパスになっています。

例えば、MathjaxをSphinxのstaticパスに置いた場合、この値は MathJax/MathJax.js となります。もし、一つ以上のSphinxドキュメントをサーバー上にホストしている場合、共通の場所にMathjaxをインストールしておくといいでしょう。

また、CDN URLではなく別の http:// 等で始まるURLを指定してもいいでしょう。

sphinx.ext.jsmath – JavaScriptを使用して数式をレンダリングします

この拡張機能はMathJax拡張と同じように動作しますが、古い jsMath パッケージを利用します。この拡張機能には、次のような設定があります。

jsmath_path

HTMLにJSMathをロードして読み込ませるための、JavaScriptファイルへのパスを設定します。デフォルト値はありません。

パスは、絶対パスでも相対パスでも指定ができます。相対パスの場合、ビルドした出力の _static ディレクトリへのパスになっています。

もしもjsMathを、Sphinxのドキュメント内の静的ファイルのフォルダに置いたとしたら、この設定値は jsMath/easy/load.js になります。もしもSphinxのドキュメントをサーバ上に何セットも設置する場合には、共有の場所にjsMathをインストールするのが賢明でしょう。