バージョン 0.5 で追加.
HTMLでは、ネイティブでは数式の記法はサポートされていません。Sphinxでは、ドキュメントの中に数式を表現するための拡張機能を２つサポートしています。
両方の数式拡張のサポートに共通する部分は、 sphinx.ext.mathbase に含まれています。他に数式をサポートを行うための拡張機能を作成する場合には、使用できるのであれば、このモジュールを再利用してください。
ノート
sphinx.ext.mathbase は extensions の設定値に追加しないでください。追加するのは、これから説明を行う sphinx.ext.pngmath もしくは sphinx.ext.jsmath を設定してください。
数式の入力言語としてはLaTeXのマークアップを利用します。これはプレーンテキストで数式を表現する記法としてはデファクトスタンダードになっています。また、LaTeX出力を行う場合には、変換をしないでそのまま利用できるというメリットもあります。
mathbase は以下の新しいマークアップの要素を定義しています:
インラインの数式のロールです。以下のようにして使用します:
ピタゴラスによって、 :math:`a^2 + b^2 = c^2` という式が成り立つことが示されました。
数式を表示するディレクティブです。この数式は１行丸ごと使って表示されます。
このディレクティブは、複数行の等式をサポートしています。複数行に記述したい場合には、空行で区切ります:
.. 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}
数式のラベルに対する、クロスリファレンスを行うためのロールです。この機能は、現在では同じドキュメント内でのみ動作します。
サンプル:
.. math:: e^{i\pi} + 1 = 0
:label: euler
数式 :eq:`euler` にある、オイラーの恒等式は、最も美しい数学の法則に選出されました。
この拡張は、LaTeXと、 dvipng を使用して、数式をPNG画像にレンダリングします。当然のことながら、この拡張を使ったドキュメントをビルドするマシンでは、この両方のプログラムが利用可能である必要があります。
この拡張用の設定値がいくつかあります。これらの設定値を変更することで、画像のビルドをカスタマイズしたりできます:
LaTeXを呼び出す場合のコマンド名です。デフォルトでは 'latex' となります。もしも latex コマンドが実行ファイルの検索パスにない場合には、フルパスを指定する必要があります。
この設定はシステムの環境に依存するものなので、この設定はシステム間でポータブルではありません。そのため、この設定値は conf.py の中で設定するのは不便なので、 sphinx-build の -D オプションを使用して渡す方が望ましいでしょう。
sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html
バージョン 0.5.1 で変更: この値にはLaTeXの実行ファイルのパスだけを含むようにして下さい。LaTeXに追加で渡したい引数は、こちらに入れないで、 pngmath_latex_args を使用してください。
LaTeXに渡す追加の引数です。リストで渡します。デフォルト値は空のリストになります。
バージョン 0.5.1 で追加.
dvipngに与える、追加の引数をリストで渡します。デフォルト値は ['-gamma 1.5', '-D 110'] で、画像をデフォルトよりも、多少暗く、サイズは少々大きくしｍさう。
追加したい引数をここで追加することができます。例えば、 '-bg Transparent' というオプションを渡すと、背景が透明なPNG画像を生成することができます。本来なら、このオプションはデフォルトで設定したいところですが、透明PNGをサポートしないバージョンのInternet Explorerもいくつか存在するために、デフォルトでは無効になっています。
ノート
もしも引数を”追加”したい場合には、デフォルトの引数と同じ設定を残したい場合には、デフォルトの引数もコピーする必要があります:
pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent']
dvipng は、レンダリングされたテキストの”深さ”を決定することができます。例えば、行の文章の中に分数を写植する場合、テキストのベースラインと、生成された画像の底辺の高さが同じであってはならず、画像はベースラインよりも少し低い位置になるべでしょう。これがTeXの世界でいう”深さ”です。もしもこのオプションが有効になっていると、ベースラインからの正しいオフセット量の 垂直揃え のスタイルで画像が生成され、HTMLドキュメントに入れられます。
残念ながら、このオプションは、 preview-latex package がインストールされていなければ動作しません。そのため、デフォルトの値は False になっています。
この拡張機能は、数式をそのままHTMLファイルに埋め込みます。JavaScriptのパッケージの jsMath がロードされ、LaTeXのマークアップが、ブラウザ上で動的に読める数式に変換します。
jsMath(と必要なフォント)はかなり巨大です。そのため、Sphinxには含まれていません。自分でインストールを行い、設定値を使って、その置き場のパスをSphinxに知らせなければなりません:
JavaScriptファイルをHTMLファイルに取り込み、JSMathをロードするために必要なオプションです。パスを設定します。デフォルト値はありません。
パスは絶対パスでも、相対パスでもどちらでも大丈夫です。相対パスの場合には、ビルド済みのドキュメントのルートが絶対パスになります。
もしもjsMathを、Sphinxのドキュメント内の静的ファイルのフォルダに置いたとしたら、この設定値は _static/jsMath/easy/load.js になります。もしもSphinxのドキュメントをサーバ上に何セットも設置する場合には、共有の場所にjsMathをインストールするのが賢明でしょう。