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
Type:
'png' | 'svg'
Default:
'png'

The output image format. 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
Type:
bool
Default:
False

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
Type:
bool
Default:
True

If false, do not add the LaTeX code as an "alt" attribute for math images.

imgmath_font_size
Type:
int
Default:
12

The font size (in pt) of the displayed math. This must be a positive integer.

imgmath_latex
Type:
str
Default:
'latex'

The command name with which to invoke LaTeX. You may need to set this to a full path if latex is not in the executable search path.

この設定はシステム間で共通にはできないため、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
Type:
Sequence[str]
Default:
()

Additional arguments to give to latex, as a list.

imgmath_latex_preamble
Type:
str
Default:
''

Additional LaTeX code to put into the preamble of the LaTeX files used to translate the math snippets. 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
Type:
str
Default:
'dvipng'

The command name to invoke 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
Type:
Sequence[str]
Default:
('-gamma', '1.5', '-D', '110', '-bg', 'Transparent')

Additional arguments to give to dvipng, as a list. The default value makes the image a bit darker and larger than 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
Type:
str
Default:
'dvisvgm'

The command name to invoke 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
Type:
Sequence[str]
Default:
('--no-fonts',)

Additional arguments to give to dvisvgm, as a list. The default value 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
Type:
bool
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
Type:
str
Default:
'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

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
Type:
dict[str, Any]
Default:
{}

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
Type:
dict[str, Any] | None
Default:
None

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.

Added in version 4.0.

mathjax2_config
Type:
dict[str, Any] | None
Default:
None

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'],
}

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

mathjax_config
Type:
dict[str, Any] | None
Default:
None

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
Type:
str
Default:
''

The path to the JavaScript file to include in the HTML files in order to load JSMath.

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

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