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 または dvisvgm を用い、数式を PNG または SVG 画像に変換します。当然ながら文書をビルドするコンピュータではこれらのプログラムが動作する必要があります。

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

imgmath_image_format¶

タイプ:: 'png' | 'svg'
デフォルト:: '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¶

タイプ:: bool
デフォルト:: 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¶

タイプ:: bool
デフォルト:: True

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

imgmath_font_size¶

タイプ:: int
デフォルト:: 12

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

imgmath_latex¶

タイプ:: str
デフォルト:: '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¶

タイプ:: Sequence[str]
デフォルト:: ()

Additional arguments to give to latex, as a list.

imgmath_latex_preamble¶

タイプ:: str
デフォルト:: ''

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¶

タイプ:: str
デフォルト:: '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¶

タイプ:: Sequence[str]
デフォルト:: ('-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¶

タイプ:: str
デフォルト:: '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¶

タイプ:: Sequence[str]
デフォルト:: ('--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¶

タイプ:: bool
デフォルト:: 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を使った数式のレンダリング¶

注意

The default version of MathJax changed from version 2 to version 3 in Sphinx 4.0, and from version 3 to version 4 in Sphinx 9.0.

You may need to override mathjax_path to load an older version, or update your configuration options. In general, MathJax v3 and v4 options are compatible.

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.

Tip

MathJax configuration can be supplied in a JavaScript file by using the mathjax_config_path option. This is useful for more complex configurations that are hard to express only using a Python dictionary, for example JavaScript functions.

mathjax_path¶

タイプ:: str
デフォルト:: 'https://cdn.jsdelivr.net/npm/mathjax@4/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を指定してもいいでしょう。

バージョン 4.0 で変更: The default version of MathJax is now version 3. To keep using MathJax v2, you must explicitly load it via this option. For example:

mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

バージョン 9.0 で変更: The default version of MathJax is now version 4. To keep using MathJax v3, you must explicitly load it via this option. For example:

mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

mathjax_options¶

タイプ:: dict[str, Any]
デフォルト:: {}

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.

mathjax4_config¶

タイプ:: dict[str, Any] | None
デフォルト:: None

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

For help converting your old MathJax configuration to to the new mathjax4_config, see Converting your old Configuration to v4.

Added in version 9.0.

mathjax3_config¶

タイプ:: dict[str, Any] | None
デフォルト:: None

The configuration options for MathJax v3 (which can be loaded via mathjax_path). If given, the dictionary is converted to a JSON object and assigned to the JavaScript variable window.MathJax.

For more information, please read Configuring MathJax.

Added in version 4.0.

mathjax2_config¶

タイプ:: dict[str, Any] | None
デフォルト:: 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'],
}

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

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

mathjax_config¶

タイプ:: dict[str, Any] | None
デフォルト:: None

Former name of mathjax2_config.

Added in version 1.8.

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

mathjax_config_path¶

タイプ:: str
デフォルト:: ''

If given, this must be the path of a JavaScript (.js) file (path relative to the configuration directory) that contains the configuration options for MathJax. Example:

mathjax_config_path = 'mathjax-config.js'

重要

The user is responsible for ensuring that the given file is compatible with the version of MathJax being used.

For more information, please read Configuring MathJax.

Added in version 9.0.

`sphinxcontrib.jsmath` -- Render math via JavaScript¶

This extension works just as the MathJax extension does, but uses the older package jsMath. jsMath is no longer actively developed, but it has the advantage that the size of the JavaScript package is much smaller than MathJax.

Added in version 0.5: The sphinx.ext.jsmath extension.

バージョン 2.0 で変更: sphinx.ext.jsmath was moved to sphinxcontrib.jsmath.

Removed in version 4.0: The alias from sphinx.ext.jsmath to sphinxcontrib.jsmath.

Config value:

jsmath_path¶

タイプ:: str
デフォルト:: ''

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

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

For example, if you put jsMath into the static path of the Sphinx docs, this value would be jsMath/easy/load.js. If you host more than one Sphinx documentation set on one server, it is advisable to install jsMath in a shared location.

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

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

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

sphinxcontrib.jsmath -- Render math via JavaScript¶

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

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

`sphinxcontrib.jsmath` -- Render math via JavaScript¶