SphinxにおけるHTML出力での数式サポート¶
バージョン 0.5 で追加.
バージョン 1.8 で変更: HTMLではないビルダーの数式サポートは sphinx-core に統合されています.よって、 mathbase 拡張はもう必要ありません.
HTMLは、ネイティブでは数式の記法をサポートしていないため、Sphinxではいくつかの拡張機能を通してHTMLドキュメントでの数式入力をサポートします。これらは、 reStructuredText math directive
と role
を使用します。
sphinx.ext.imgmath
-- 数式を画像にレンダリングします¶
バージョン 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 executinglatex
on the TeX mathematical mark-up then (depending on the requested format) either dvipng or dvisvgm.
- imgmath_use_preview¶
dvipng
anddvisvgm
both have the ability to collect from LaTeX the "depth" of the rendered math: an inline image should use this "depth" in avertical-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 isFalse
but it is strongly recommended to set it toTrue
.バージョン 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 customimgmath_latex_preamble
, you can setimgmath_latex
to'dvilualatex'
, but must then setimgmath_image_format
to'svg'
. Note: this has only been tested withdvisvgm 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 theimgmath_latex_args
list of the command options. The'svg'
imgmath_image_format
is required. Also, you may need thedvisvgm
binary to be relatively recent (testing was done only with its3.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 ifdvipng
is not in the executable search path. This option is only used whenimgmath_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 whenimgmath_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 ifdvisvgm
is not in the executable search path. This option is only used whenimgmath_image_format
is'svg'
.
- imgmath_dvisvgm_args¶
Additional arguments to give to dvisvgm, as a list. The default value is
['--no-fonts']
, which means thatdvisvgm
will render glyphs as path elements (cf the dvisvgm FAQ). This option is used only whenimgmath_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.バージョン 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
).
バージョン 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.
- 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-......', }
デフォルトは空です (
{}
) 。バージョン 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) 。
バージョン 4.0 で追加.
- mathjax2_config¶
The configuration options for MathJax v2 (which can be loaded via
mathjax_path
). The value is used as a parameter ofMathJax.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) 。
バージョン 4.0 で追加:
mathjax_config
has been renamed tomathjax2_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.バージョン 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をインストールするのが賢明でしょう。