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

Added in version 0.5.

バージョン 1.8 で変更: HTMLではないビルダーの数式サポートは sphinx-core に統合されています．よって、 mathbase 拡張はもう必要ありません．

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

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

Added in version 1.4.

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

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

imgmath_image_format

The output image format. The default is 'png'. It should be either 'png' or 'svg'. The image is produced by first executing latex on the TeX mathematical mark-up then (depending on the requested format) either dvipng or dvisvgm.

imgmath_use_preview

dvipng and dvisvgm both have the ability to collect from LaTeX the "depth" of the rendered math: an inline image should use this "depth" in a vertical-align style to get correctly aligned with surrounding text.

This mechanism requires the LaTeX preview package (available as preview-latex-style on Ubuntu xenial). Therefore, the default for this option is False but it is strongly recommended to set it to True.

バージョン 2.2 で変更: This option can be used with the '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の実行ファイルのパスだけを含むようにして下さい。LaTeXに追加で渡したい引数は、こちらに入れないで、 imgmath_latex_args を使用してください。

ヒント

To use OpenType Math fonts with unicode-math, via a custom imgmath_latex_preamble, you can set imgmath_latex to 'dvilualatex', but must then set imgmath_image_format to 'svg'. Note: this has only been tested with dvisvgm 3.0.3. It significantly increases image production duration compared to using standard 'latex' with traditional TeX math fonts.

ヒント

Some fancy LaTeX mark-up (an example was reported which used TikZ to add various decorations to the equation) require multiple runs of the LaTeX executable. To handle this, set this configuration setting to 'latexmk' (or a full path to it) as this Perl script reliably chooses dynamically how many latex runs are needed.

バージョン 6.2.0 で変更: Using 'xelatex' (or a full path to it) is now supported. But you must then add '-no-pdf' to the imgmath_latex_args list of the command options. The 'svg' imgmath_image_format is required. Also, you may need the dvisvgm binary to be relatively recent (testing was done only with its 3.0.3 release).

注釈

Regarding the previous note, it is currently not supported to use latexmk with option -xelatex.

imgmath_latex_args

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

imgmath_latex_preamble

Additional LaTeX code to put into the preamble of the LaTeX files used to translate the math snippets. This is left empty by default. Use it e.g. to add packages which modify the fonts used for math, such as '\\usepackage{newtxsf}' for sans-serif fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed, the default LaTeX math fonts have rather thin glyphs which (in HTML output) often do not match well with the font for text.

imgmath_dvipng

The command name to invoke dvipng. The default is 'dvipng'; you may need to set this to a full path if dvipng is not in the executable search path. This option is only used when imgmath_image_format is set to 'png'.

imgmath_dvipng_args

Additional arguments to give to dvipng, as a list. The default value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'] which makes the image a bit darker and larger then it is by default (this compensates somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a transparent background. This option is used only when imgmath_image_format is 'png'.

imgmath_dvisvgm

The command name to invoke dvisvgm. The default is 'dvisvgm'; you may need to set this to a full path if dvisvgm is not in the executable search path. This option is only used when imgmath_image_format is 'svg'.

imgmath_dvisvgm_args

Additional arguments to give to dvisvgm, as a list. The default value is ['--no-fonts'], which means that dvisvgm will render glyphs as path elements (cf the dvisvgm FAQ). This option is used only when imgmath_image_format is 'svg'.

imgmath_embed

Default: False. If true, encode LaTeX output images within HTML files (base64 encoded) and do not save separate png/svg files to disk.

Added in version 5.2.

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

警告

Version 4.0 changes the version of MathJax used to version 3. You may need to override mathjax_path to https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or update your configuration options for version 3 (see mathjax3_config).

Added in version 1.1.

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

Because MathJax (and the necessary fonts) is very large, it is not included in Sphinx but is set to automatically include it from a third-party site.

注意

You should use the math directive and role, not the native MathJax $$, \(, etc.

mathjax_path

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

The default is the https:// URL that loads the JS files from the jsdelivr Content Delivery Network. See the MathJax Getting Started page for details. If you want MathJax to be available offline or without including resources from a third-party site, you have to download it and set this value to a different path.

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

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

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

mathjax_options

mathjax における script タグへのオプションです。例えば、integrity オプションを次のように設定できます:

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

デフォルトは空です ({}) 。

Added in version 1.8.

バージョン 4.4.1 で変更: Allow to change the loading method (async or defer) of MathJax if "async" or "defer" key is set.

mathjax3_config

The configuration options for MathJax v3 (which is used by default). The given dictionary is assigned to the JavaScript variable window.MathJax. For more information, please read Configuring MathJax.

デフォルトは空です (not configured) 。

Added in version 4.0.

mathjax2_config

The configuration options for MathJax v2 (which can be loaded via mathjax_path). The value is used as a parameter of MathJax.Hub.Config(). For more information, please read Using in-line configuration options.

例えば:

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

デフォルトは空です (not configured) 。

Added in version 4.0: mathjax_config has been renamed to mathjax2_config.

mathjax_config

Former name of mathjax2_config.

For help converting your old MathJax configuration to to the new mathjax3_config, see Converting Your v2 Configuration to v3.

Added in version 1.8.

バージョン 4.0 で変更: This has been renamed to mathjax2_config. mathjax_config is still supported for backwards compatibility.

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

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

jsmath_path

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

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

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