Sphinx中HTML输出的数学支持¶
在 0.5 版本加入.
在 1.8 版本发生变更: 对非HTML构建器的数学支持集成到sphinx核心中。所以不再需要mathbase扩展。
由于HTML在任何方面都不支持数学表示法，Sphinx为HTML文档提供了数学支持，并提供了几个扩展。这些方法使用了restructedText math directive 和 role。
sphinx.ext.imgmath -- 将数学渲染为图像¶
在 1.4 版本加入.
这个插件通过LaTeX和 dvipng 或 dvisvgm 将数学呈现为PNG或SVG图像。这当然意味着生成文档的计算机必须同时具有这两个程序。
您可以设置各种配置值来影响图像的构建方式：
- imgmath_image_format¶
- 类型:
'png' | 'svg'- 默认:
'png'
输出图像格式。它应该是
'png'或'svg'。该图像首先通过对TeX数学标记执行latex然后（根据请求的格式）使用 dvipng 或 dvisvgm 生成。
- imgmath_use_preview¶
- 类型:
bool- 默认:
False
dvipng和dvisvgm都能够从LaTeX中收集渲染数学的“深度”：内联图像应该以垂直对齐样式使用此“深度”，以便与周围的文本正确对齐。此机制需要 LaTeX preview package （在Ubuntu xenial上作为
preview-latex-style提供）。因此，此选项的默认值为False，但强烈建议将其设置为True。在 2.2 版本发生变更: 此选项可与
'svg'一起使用imgmath_image_format。
- imgmath_add_tooltips¶
- 类型:
bool- 默认:
True
如果为false，则不将LaTeX代码作为数学图像的“alt”属性添加。
- imgmath_font_size¶
- 类型:
int- 默认:
12
显示数学的字体大小（以
pt为单位）。这必须是一个正整数。
- imgmath_latex¶
- 类型:
str- 默认:
'latex'
用于调用LaTeX的命令名称。如果
latex不在可执行文件搜索路径中，则可能需要将其设置为完整路径。由于此设置在系统之间不可移植，因此通常在
conf.py中设置它是没有用的；相反，在 sphinx-build 命令行中通过-D选项给出它应该更可取，如下所示：sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build
此值只应包含指向latex可执行文件的路径，而不应包含其他参数；为此，请使用
imgmath_latex_args。提示
要通过自定义
imgmath_latex_preamble使用unicode-math的 OpenType Math fonts，可以将imgmath_latex设置为'dvilualatex'，但必须将imgmath_image_format设置为'svg'。注意：这仅在dvisvgm 3.0.3中进行了测试。与使用传统TeX数学字体的标准'latex'相比，它显著增加了图像生成时间。提示
一些花哨的LaTeX标记（有一个例子是使用TikZ为等式添加各种装饰）需要多次运行LaTeX可执行文件。要处理此问题，请将此配置设置设置为
'latexmk'（或指向它的完整路径），因为此Perl脚本可以可靠地动态选择所需的latex运行次数。在 6.2.0 版本发生变更: 现在支持使用
'xelatex'（或指向它的完整路径）。但您必须将'-no-pdf'添加到imgmath_latex_args命令选项列表中。需要'svg'imgmath_image_format。此外，您可能需要相对较新的dvisvgm二进制文件（仅使用其3.0.3版本进行了测试）。备注
关于前面的注意事项，目前不支持将
latexmk与选项-xelatex一起使用。
- imgmath_latex_args¶
- 类型:
Sequence[str]- 默认:
()
要提供给latex的其他参数，以列表的方式。
- imgmath_latex_preamble¶
- 类型:
str- 默认:
''
要添加到用于转换数学片段的LaTeX文件前言中的其他LaTeX代码。例如，使用它来添加修改用于数学的字体的软件包，例如用于无衬线字体的
'\\usepackage{newtxsf}'或用于衬线字体的'\\usepackage{fouriernc}'。实际上，默认的LaTeX数学字体具有相当细的字形，在HTML输出中通常与文本字体不太匹配。
- imgmath_dvipng¶
- 类型:
str- 默认:
'dvipng'
用于调用
dvipng的命令名称。如果dvipng不在可执行文件搜索路径中，则可能需要将其设置为完整路径。
- imgmath_dvipng_args¶
- 类型:
Sequence[str]- 默认:
('-gamma', '1.5', '-D', '110', '-bg', 'Transparent')
要提供给dvipng的其他参数，以列表的方式。默认值使图像比默认情况下更暗更大（这在某种程度上补偿了默认LaTeX数学字体的细度），并生成具有透明背景的PNG。此选项仅在
imgmath_image_format为'png'时使用。
- imgmath_dvisvgm¶
- 类型:
str- 默认:
'dvisvgm'
用于调用
dvisvgm的命令名称。如果dvisvgm不在可执行文件搜索路径中，则可能需要将其设置为完整路径。此选项仅在imgmath_image_format为'svg'时使用。
- imgmath_dvisvgm_args¶
- 类型:
Sequence[str]- 默认:
('--no-fonts',)
要提供给dvisvgm的其他参数，以列表的方式。默认值意味着
dvisvgm将把字形渲染为路径元素（参见 dvisvgm FAQ）。此选项仅在imgmath_image_format为'svg'时使用。
- imgmath_embed¶
- 类型:
bool- 默认:
False
如果为true，则在HTML文件中对LaTeX输出图像进行编码（base64编码），并且不将单独的png/svg文件保存到磁盘。
在 5.2 版本加入.
sphinx.ext.mathjax -- 通过JavaScript呈现数学¶
注意
MathJax的默认版本在Sphinx 4.0中从版本2更改为版本3，在Sphinx 9.0中从版本3更改为版本4。
您可能需要覆盖 mathjax_path 以加载较旧的版本，或更新您的 configuration options。通常，MathJax v3和v4选项是兼容的。
在 1.1 版本加入.
这个扩展将数学原样放入HTML文件中。然后加载JavaScript包 MathJax，并在浏览器中实时地将LaTeX标记转换为可读的math。
因为MathJax（以及必要的字体）非常大，所以Sphinx中没有包含它，而是设置为从第三方站点自动包含它。
小技巧
可以使用 mathjax_config_path 选项在JavaScript文件中提供MathJax配置。这对于仅使用Python字典难以表达的更复杂的配置非常有用，例如JavaScript函数。
- mathjax_path¶
- 类型:
str- 默认:
'https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js'
要包含在HTML文件中以加载MathJax的JavaScript文件的路径。
默认值是
https://URL，它从 jsdelivr 内容分发网络加载JS文件。详情请参阅 MathJax Getting Started page 。如果您希望MathJax可离线使用或不包含来自第三方站点的资源，则必须下载它并将此值设置为不同的路径。路径可以是绝对路径，也可以是相对路径；如果是相对路径，则路径是相对于生成文档的
_static目录。例如，如果将MathJax放入Sphinx文档的静态路径中，则该值将为
MathJax/MathJax.js。如果在一台服务器上托管多个Sphinx文档集，建议在共享位置安装MathJax。您还可以提供与CDN URL不同的完整的
https://URL。在 4.0 版本发生变更: MathJax的默认版本现在是版本3。要继续使用MathJax v2，必须通过此选项显式加载它。例如：
mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
在 9.0 版本发生变更: MathJax的默认版本现在是版本4。要继续使用MathJax v3，必须通过此选项显式加载它。例如：
mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'
- mathjax_options¶
- 类型:
dict[str, Any]- 默认:
{}
为mathjax编写标记脚本的选项。例如，可以使用以下设置设置设置完整性选项：
mathjax_options = { 'integrity': 'sha384-......', }在 1.8 版本加入.
在 4.4.1 版本发生变更: 允许更改MathJax的加载方法（异步或延迟），如果设置了“async”或“defer”键。
- mathjax4_config¶
- 类型:
dict[str, Any] | None- 默认:
None
MathJax v4的配置选项（默认使用）。给定的字典分配给JavaScript变量
window.MathJax。有关更多信息，请阅读 Configuring MathJax 。有关将旧的MathJax配置转换为新的
mathjax4_config的帮助，请参阅 Converting your old Configuration to v4 。在 9.0 版本加入.
- mathjax3_config¶
- 类型:
dict[str, Any] | None- 默认:
None
MathJax v3的配置选项（可以通过
mathjax_path加载）。如果给定，该字典将转换为JSON对象并分配给JavaScript变量window.MathJax。有关更多信息，请阅读 Configuring MathJax 。
在 4.0 版本加入.
- mathjax2_config¶
- 类型:
dict[str, Any] | None- 默认:
None
MathJax v2的配置选项（可以通过
mathjax_path加载）。该值用作MathJax.Hub.Config()的参数。有关更多信息，请阅读 Using in-line configuration options 。例如：
mathjax2_config = { 'extensions': ['tex2jax.js'], 'jax': ['input/TeX', 'output/HTML-CSS'], }有关将旧的MathJax配置转换为新的
mathjax3_config的帮助，请参阅 Converting Your v2 Configuration to v3 。在 4.0 版本加入:
mathjax_config已重命名为mathjax2_config。
- mathjax_config¶
- 类型:
dict[str, Any] | None- 默认:
None
mathjax2_config的前身名称。在 1.8 版本加入.
在 4.0 版本发生变更: 它已重命名为
mathjax2_config。为了向后兼容，仍然支持mathjax_config。
- mathjax_config_path¶
- 类型:
str- 默认:
''
如果给定，这必须是JavaScript（
.js）文件的路径（相对于 configuration directory 的路径），其中包含MathJax的配置选项。例子：mathjax_config_path = 'mathjax-config.js'
重要
用户有责任确保给定的文件与所使用的MathJax版本兼容。
有关更多信息，请阅读 Configuring MathJax 。
在 9.0 版本加入.
sphinxcontrib.jsmath -- 通过JavaScript呈现数学¶
这个扩展的工作方式与MathJax扩展相同，但使用较旧的 jsMath 包。jsMath不再积极开发，但它的优点是JavaScript包的大小远小于MathJax。
在 0.5 版本加入: sphinx.ext.jsmath 扩展。
在 2.0 版本发生变更: sphinx.ext.jsmath 已移至 sphinxcontrib.jsmath。
在版本 4.0 移除: 从 sphinx.ext.jsmath 到 sphinxcontrib.jsmath 的别名。
配置值：
- jsmath_path¶
- 类型:
str- 默认:
''
要包含在HTML文件中以加载JSMath的JavaScript文件的路径。
路径可以是绝对路径，也可以是相对路径；如果是相对路径，则路径是相对于生成文档的
_static目录。例如，如果将jsMath放入Sphinx文档的静态路径中，则该值将为
jsMath/easy/load.js。如果在一台服务器上托管多个Sphinx文档集，建议在共享位置安装jsMath。