Sphinx 文档中 HTML 输出的数学支持¶

版本 0.5 中新增。

版本 1.8 中更改: 非 HTML 构建器的数学支持已集成到 sphinx-core 中。因此，不再需要 mathbase 扩展。

由于 HTML 本身无法以任何方式原生支持数学符号，因此 Sphinx 通过几个扩展为 HTML 文档提供了数学支持。这些扩展使用 reStructuredText 的数学 指令 和 角色。

`sphinx.ext.imgmath` – 将数学公式渲染为图像¶

版本 1.4 中新增。

此扩展通过 LaTeX 和 dvipng 或 dvisvgm 将数学公式渲染为 PNG 或 SVG 图像。当然，这意味着构建文档的计算机必须同时具备这两个程序。

您可以设置各种配置值来影响图像的构建方式

imgmath_image_format¶: 输出图像格式。默认为 'png'。它应该是 'png' 或 'svg'。图像的生成过程首先是使用 latex 处理 TeX 数学标记，然后（根据请求的格式）使用 dvipng 或 dvisvgm。

imgmath_use_preview¶

dvipng 和 dvisvgm 都能够从 LaTeX 中获取渲染后的数学公式的“深度”：内联图像应在 vertical-align 样式中使用此“深度”以使其与周围文本正确对齐。

此机制需要 LaTeX 预览包（在 Ubuntu xenial 上可用作 preview-latex-style）。因此，此选项的默认值为 False，但强烈建议将其设置为 True。

版本 2.2 中更改: 此选项可与 'svg' imgmath_image_format 一起使用。

imgmath_add_tooltips¶: 默认值：True。如果为 false，则不将 LaTeX 代码作为数学图像的“alt”属性添加。

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 可执行文件的路径，不包含其他参数；为此目的，请使用 imgmath_latex_args。

提示

要通过自定义的 imgmath_latex_preamble 使用 OpenType 数学字体和 unicode-math，可以将 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¶: 传递给 latex 的其他参数，以列表形式给出。默认为空列表。

imgmath_latex_preamble¶: 要添加到用于转换数学片段的 LaTeX 文件的前言中的其他 LaTeX 代码。默认情况下为空。例如，可以使用它来添加修改数学公式字体使用的包，例如 '\\usepackage{newtxsf}' 用于无衬线字体，或 '\\usepackage{fouriernc}' 用于衬线字体。实际上，默认的 LaTeX 数学字体具有相当细的字形，这些字形（在 HTML 输出中）通常与文本的字体不匹配。

imgmath_dvipng¶: 调用dvipng的命令名称。默认值为'dvipng'；如果dvipng不在可执行文件搜索路径中，则可能需要将其设置为完整路径。仅当imgmath_image_format设置为'png'时使用此选项。

imgmath_dvipng_args¶: 传递给dvipng的附加参数，以列表形式给出。默认值为['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']，它使图像比默认情况下稍微暗一些且更大（这在一定程度上弥补了默认LaTeX数学字体过细的问题），并生成具有透明背景的PNG。仅当imgmath_image_format为'png'时使用此选项。

imgmath_dvisvgm¶: 调用dvisvgm的命令名称。默认值为'dvisvgm'；如果dvisvgm不在可执行文件搜索路径中，则可能需要将其设置为完整路径。仅当imgmath_image_format设置为'svg'时使用此选项。

imgmath_dvisvgm_args¶: 传递给dvisvgm的附加参数，以列表形式给出。默认值为['--no-fonts']，这意味着dvisvgm将以路径元素的形式渲染字形（参见dvisvgm FAQ）。仅当imgmath_image_format为'svg'时使用此选项。

imgmath_embed¶: 默认值：False。如果为真，则将LaTeX输出图像编码到HTML文件（Base64编码）中，并且不将单独的png/svg文件保存到磁盘。

版本5.2中新增。

`sphinx.ext.mathjax` – 通过JavaScript渲染数学公式¶

警告

版本4.0将使用的MathJax版本更改为版本3。您可能需要将mathjax_path覆盖为https://cdn.jsdelivr.net.cn/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML或更新版本3的配置选项（请参阅mathjax3_config）。

版本1.1中新增。

此扩展将数学公式原样放入HTML文件中。然后加载JavaScript包MathJax，并在浏览器中实时将LaTeX标记转换为可读的数学公式。

由于MathJax（以及必要的字体）非常庞大，因此它未包含在Sphinx中，而是设置为自动从第三方站点包含它。

注意

您应该使用数学指令和角色，而不是原生的MathJax $$、\(等。

mathjax_path¶

要包含在HTML文件中以加载MathJax的JavaScript文件的路径。

默认值为从jsdelivr内容交付网络加载JS文件的https:// URL。有关详细信息，请参见MathJax入门页面。如果您希望MathJax能够离线使用或无需从第三方站点包含资源，则必须下载它并将此值设置为不同的路径。

路径可以是绝对路径或相对路径；如果为相对路径，则相对于构建文档的_static目录。

例如，如果您将MathJax放入Sphinx文档的静态路径中，则此值将为MathJax/MathJax.js。如果您在一台服务器上托管多个Sphinx文档集，建议将MathJax安装在共享位置。

您还可以提供与CDN URL不同的完整https:// URL。

mathjax_options¶

mathjax脚本标签的选项。例如，您可以使用以下设置设置完整性选项

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

默认值为空（{}）。

版本1.8中新增。

版本4.4.1中已更改：如果设置了“async”或“defer”键，则允许更改MathJax的加载方法（异步或延迟）。

mathjax3_config¶

MathJax v3的配置选项（默认使用）。给定的字典被分配给JavaScript变量window.MathJax。有关更多信息，请阅读配置MathJax。

默认值为未配置（空）。

版本4.0中新增。

mathjax2_config¶

MathJax v2的配置选项（可以通过mathjax_path加载）。该值用作MathJax.Hub.Config()的参数。有关更多信息，请阅读使用内联配置选项。

例如

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

默认值为未配置（空）。

版本4.0中新增： mathjax_config已重命名为mathjax2_config。

mathjax_config¶

mathjax2_config的前一个名称。

有关将旧的MathJax配置转换为新的mathjax3_config的帮助，请参见将您的v2配置转换为v3。

版本1.8中新增。

版本4.0中已更改：此项已重命名为mathjax2_config。mathjax_config仍支持向后兼容。

`sphinx.ext.jsmath` – 通过JavaScript渲染数学公式¶

此扩展的工作原理与MathJax扩展相同，但使用较旧的包jsMath。它提供以下配置值

jsmath_path¶

要包含在HTML文件中以加载JSMath的JavaScript文件的路径。没有默认值。

路径可以是绝对路径或相对路径；如果为相对路径，则相对于构建文档的_static目录。

例如，如果您将JSMath放入Sphinx文档的静态路径中，则此值将为jsMath/easy/load.js。如果您在一台服务器上托管多个Sphinx文档集，建议将jsMath安装在共享位置。

Sphinx 文档中 HTML 输出的数学支持¶

sphinx.ext.imgmath – 将数学公式渲染为图像¶

sphinx.ext.mathjax – 通过JavaScript渲染数学公式¶

sphinx.ext.jsmath – 通过JavaScript渲染数学公式¶

`sphinx.ext.imgmath` – 将数学公式渲染为图像¶

`sphinx.ext.mathjax` – 通过JavaScript渲染数学公式¶

`sphinx.ext.jsmath` – 通过JavaScript渲染数学公式¶