Sphinx での HTML 出力における数式サポート

バージョン 0.5 で追加.

バージョン 1.8 で変更: HTML 以外のビルダーの数式サポートは sphinx-core に統合されました。したがって、mathbase 拡張機能は不要になりました。

数学的表記は HTML でネイティブにサポートされていないため、Sphinx はいくつかの拡張機能を使用して HTML ドキュメントに数式サポートを提供します。これらは、reStructuredText の math directive と role を使用します。

sphinx.ext.imgmath – 数式を画像としてレンダリング

バージョン 1.4 で追加.

この拡張機能は、LaTeX と dvipng または dvisvgm を使用して数式を PNG または SVG 画像にレンダリングします。これはもちろん、ドキュメントがビルドされるコンピューターで両方のプログラムが利用可能である必要があることを意味します。

画像の作成方法に影響を与えるために設定できるさまざまな構成値があります

imgmath_image_format

出力画像形式。デフォルトは 'png' です。 'png' または 'svg' のいずれかである必要があります。画像は、最初に TeX の数式マークアップに対して latex を実行し、次に (要求された形式に応じて) dvipng または dvisvgm のいずれかによって生成されます。

imgmath_use_preview

dvipng と dvisvgm は両方とも、レンダリングされた数式の "深さ" を LaTeX から収集する機能を備えています。インライン画像は、周囲のテキストと正しく整列するために、この "深さ" を vertical-align スタイルで使用する必要があります。

このメカニズムには、LaTeX preview パッケージ (Ubuntu xenial では preview-latex-style として利用可能) が必要です。したがって、このオプションのデフォルトは False ですが、True に設定することを強くお勧めします。

バージョン 2.2 で変更: このオプションは、'svg' imgmath_image_format で使用できます。

imgmath_add_tooltips

デフォルト: True。false の場合、数式画像の「alt」属性として LaTeX コードを追加しないでください。

imgmath_font_size

表示される数式のフォントサイズ (pt 単位)。デフォルト値は 12 です。正の整数である必要があります。

imgmath_latex

LaTeX を呼び出すコマンド名。デフォルトは 'latex' です。 latex が実行可能検索パスにない場合は、これをフルパスに設定する必要がある場合があります。

この設定はシステム間で移植可能ではないため、通常は conf.py で設定しても役に立ちません。代わりに、sphinx-build コマンドラインで -D オプションを介して次のように指定する方が望ましいでしょう。

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

この値には、latex 実行可能ファイルへのパスのみを含める必要があります。それ以上の引数は含めないでください。その目的には imgmath_latex_args を使用してください。

ヒント

OpenType 数学フォント を、カスタムの imgmath_latex_preamble を介して unicode-math で使用するには、imgmath_latex を 'dvilualatex' に設定できますが、その場合は imgmath_image_format を 'svg' に設定する必要があります。注: これは dvisvgm 3.0.3 でのみテストされています。従来の TeX 数学フォントで標準の 'latex' を使用する場合と比較して、画像作成時間が大幅に長くなります。

ヒント

一部の高度な LaTeX マークアップ (数式にさまざまな装飾を追加するために TikZ を使用した例が報告されました) では、LaTeX 実行可能ファイルの複数回の実行が必要です。これを処理するには、この構成設定を 'latexmk' (またはそのフルパス) に設定します。この Perl スクリプトは、必要な LaTeX の実行回数を動的に確実に選択するためです。

バージョン 6.2.0 で変更: 'xelatex' （またはそのフルパス）の使用がサポートされるようになりました。ただし、その場合は、imgmath_latex_args コマンドオプションのリストに '-no-pdf' を追加する必要があります。'svg' の imgmath_image_format が必要です。また、dvisvgm バイナリが比較的最近のものである必要があるかもしれません（テストは 3.0.3 リリースでのみ行われました）。

注記

前の注記に関して、現在、オプション -xelatex 付きで latexmk を使用することはサポートされていません。

imgmath_latex_args

latexに渡す追加の引数をリストとして指定します。デフォルトは空のリストです。

imgmath_latex_preamble

数式スニペットの変換に使用される LaTeX ファイルのプリアンブルに配置する追加の LaTeX コード。デフォルトでは空になっています。例えば、サンセリフフォントの場合は '\\usepackage{newtxsf}'、セリフフォントの場合は '\\usepackage{fouriernc}' など、数式に使用されるフォントを変更するパッケージを追加するために使用します。実際、デフォルトの LaTeX 数式フォントは、グリフがかなり薄く、（HTML出力では）テキストのフォントと一致しないことがよくあります。

imgmath_dvipng

dvipng を起動するためのコマンド名。デフォルトは 'dvipng' です。 dvipng が実行可能ファイルの検索パスにない場合は、これをフルパスに設定する必要があるかもしれません。このオプションは、imgmath_image_format が 'png' に設定されている場合にのみ使用されます。

imgmath_dvipng_args

dvipngに渡す追加の引数をリストとして指定します。デフォルト値は ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'] です。これにより、画像がデフォルトよりも少し暗く、大きくなります（これはデフォルトの LaTeX 数式フォントの薄さをある程度補正します）。また、透明な背景を持つ PNG が生成されます。このオプションは、imgmath_image_format が 'png' の場合にのみ使用されます。

imgmath_dvisvgm

dvisvgm を起動するためのコマンド名。デフォルトは 'dvisvgm' です。dvisvgm が実行可能ファイルの検索パスにない場合は、これをフルパスに設定する必要があるかもしれません。このオプションは、imgmath_image_format が 'svg' に設定されている場合にのみ使用されます。

imgmath_dvisvgm_args

dvisvgmに渡す追加の引数をリストとして指定します。デフォルト値は ['--no-fonts'] です。これは、dvisvgm がグリフをパス要素としてレンダリングすることを意味します（dvisvgm FAQ を参照）。このオプションは、imgmath_image_format が 'svg' の場合にのみ使用されます。

imgmath_embed

デフォルト： False。true の場合、LaTeX 出力画像を HTML ファイル内に（base64 エンコードで）エンコードし、個別の png/svg ファイルをディスクに保存しません。

バージョン 5.2 で追加。

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

警告

バージョン 4.0 では、使用される MathJax のバージョンがバージョン 3 に変更されます。mathjax_path を https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML に上書きするか、バージョン 3 の設定オプションを更新する必要がある場合があります（mathjax3_config を参照）。

バージョン 1.1 で追加。

この拡張機能は、数式をそのまま HTML ファイルに入れます。その後、JavaScript パッケージ MathJax がロードされ、LaTeX マークアップがブラウザで読み取り可能な数式に変換されます。

MathJax（および必要なフォント）は非常に大きいため、Sphinx には含まれていませんが、サードパーティのサイトから自動的に含めるように設定されています。

注意

ネイティブの MathJax $$, \( などではなく、math ディレクティブ および ロール を使用する必要があります。

mathjax_path

MathJax をロードするために HTML ファイルに含める JavaScript ファイルへのパス。

デフォルトは、jsdelivr コンテンツ配信ネットワークから JS ファイルをロードする https:// URL です。詳細については、MathJax Getting Started ページを参照してください。MathJax をオフラインで利用できるようにするか、サードパーティのサイトからのリソースを含めずに利用できるようにする場合は、ダウンロードしてこの値を別のパスに設定する必要があります。

パスは絶対パスまたは相対パスにできます。相対パスの場合、ビルドされたドキュメントの _static ディレクトリからの相対パスになります。

たとえば、MathJax を Sphinx ドキュメントの静的パスに配置した場合、この値は MathJax/MathJax.js になります。1つのサーバーで複数の Sphinx ドキュメントセットをホストしている場合は、MathJax を共有の場所にインストールすることをお勧めします。

CDN URL とは異なるフル https:// URL を指定することもできます。

mathjax_options

mathjax のスクリプトタグのオプション。たとえば、次の設定でintegrityオプションを設定できます。

mathjax_options = {
    'integrity': 'sha384-......',
}

デフォルトは空（{}）です。

バージョン 1.8 で追加。

バージョン 4.4.1 で変更: 「async」または「defer」キーが設定されている場合、MathJax のロード方法（async または defer）を変更できます。

mathjax3_config

MathJax v3（デフォルトで使用されます）の設定オプション。指定されたディクショナリは、JavaScript 変数 window.MathJax に割り当てられます。詳細については、MathJax の設定をお読みください。

デフォルトは空（設定なし）です。

バージョン 4.0 で追加。

mathjax2_config

MathJax v2（mathjax_path を介してロードできます）の設定オプション。この値は、MathJax.Hub.Config() のパラメータとして使用されます。詳細については、インライン設定オプションの使用をお読みください。

例

mathjax2_config = {
    'extensions': ['tex2jax.js'],
    'jax': ['input/TeX', 'output/HTML-CSS'],
}

デフォルトは空（設定なし）です。

バージョン 4.0 で追加: mathjax_config が mathjax2_config に名前変更されました。

mathjax_config

mathjax2_config の以前の名前。

古い MathJax 設定を新しい mathjax3_config に変換する方法については、v2 設定から v3 への変換を参照してください。

バージョン 1.8 で追加。

バージョン 4.0 で変更: これが mathjax2_config に名前変更されました。mathjax_config は後方互換性のために引き続きサポートされています。

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

この拡張機能は MathJax 拡張機能とまったく同じように機能しますが、古いパッケージ jsMath を使用します。次の設定値を提供します。

jsmath_path

JSMath をロードするために HTML ファイルに含める JavaScript ファイルへのパス。デフォルトはありません。

パスは絶対パスまたは相対パスにできます。相対パスの場合、ビルドされたドキュメントの _static ディレクトリからの相対パスになります。

たとえば、JSMath を Sphinx ドキュメントの静的パスに配置した場合、この値は jsMath/easy/load.js になります。1つのサーバーで複数の Sphinx ドキュメントセットをホストしている場合は、jsMath を共有の場所にインストールすることをお勧めします。