Sphinx HTML 输出的数学支持¶

添加于版本 0.5。

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

由于 HTML 本身并不原生支持数学符号，Sphinx 通过几个扩展为 HTML 文档提供数学支持。这些扩展使用 reStructuredText 数学 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¶

类型:: 布尔值
默认:: False

dvipng 和 dvisvgm 都具有从 LaTeX 收集渲染数学公式的“深度”的能力：内联图像应在 vertical-align 样式中使用此“深度”，以便与周围文本正确对齐。

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

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

imgmath_add_tooltips¶

类型:: 布尔值
默认:: True

如果为 false，则不要将 LaTeX 代码添加为数学图像的“alt”属性。

imgmath_font_size¶

类型:: 整数
默认:: 12

显示的数学公式的字体大小（以 pt 为单位）。这必须是正整数。

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。

提示

要将 OpenType Math 字体与 unicode-math 结合使用，通过自定义 imgmath_latex_preamble，您可以将 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¶

类型:: 字符串
默认:: ''

要放入用于翻译数学代码片段的 LaTeX 文件序言中的其他 LaTeX 代码。例如，使用它来添加修改用于数学公式的字体的包，例如用于无衬线字体的 '\\usepackage{newtxsf}'，或用于衬线字体的 '\\usepackage{fouriernc}'。实际上，默认的 LaTeX 数学字体具有相当细的字形，这（在 HTML 输出中）通常与文本字体不太匹配。

imgmath_dvipng¶

类型:: 字符串
默认:: 'dvipng'

用于调用 dvipng 的命令名称。如果 dvipng 不在可执行搜索路径中，您可能需要将其设置为完整路径。仅当 imgmath_image_format 设置为 'png' 时才使用此选项。

imgmath_dvipng_args¶

类型:: Sequence[str]
默认:: ('-gamma', '1.5', '-D', '110', '-bg', 'Transparent')

要传递给 dvipng 的其他参数，以列表形式。默认值使图像比默认情况下稍暗且稍大（这在一定程度上弥补了默认 LaTeX 数学字体的细度），并生成具有透明背景的 PNG。仅当 imgmath_image_format 为 'png' 时才使用此选项。

imgmath_dvisvgm¶

类型:: 字符串
默认:: 'dvisvgm'

用于调用 dvisvgm 的命令名称。如果 dvisvgm 不在可执行搜索路径中，您可能需要将其设置为完整路径。仅当 imgmath_image_format 为 'svg' 时才使用此选项。

imgmath_dvisvgm_args¶

类型:: Sequence[str]
默认:: ('--no-fonts',)

要传递给 dvisvgm 的其他参数，以列表形式。默认值表示 dvisvgm 将字形渲染为路径元素（参见 dvisvgm FAQ）。仅当 imgmath_image_format 为 'svg' 时才使用此选项。

imgmath_embed¶

类型:: 布尔值
默认:: False

如果为 true，则将 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 中，而是设置为自动从第三方站点包含它。

注意

您应该使用 math directive 和 role，而不是原生的 MathJax $$、\( 等。

mathjax_path¶

类型:: 字符串
默认:: 'https://cdn.jsdelivr.net.cn/npm/mathjax@3/es5/tex-mml-chtml.js'

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

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

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

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

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

mathjax_options¶

类型:: dict[str, Any]
默认:: {}

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

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

添加于版本 1.8。

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

mathjax3_config¶

类型:: dict[str, Any] | None
默认:: None

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

添加于版本 4.0。

mathjax2_config¶

类型:: dict[str, Any] | None
默认:: None

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¶

类型:: dict[str, Any] | None
默认:: None

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 渲染数学公式¶