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' | 'svg'
默认:: 'png'

输出图像格式。应为'png'或'svg'。图像首先通过在 TeX 数学标记上执行latex，然后（根据请求的格式）使用dvipng或dvisvgm生成。

imgmath_use_preview¶

类型:: bool
默认:: False

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

此机制需要LaTeX 预览包（在 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中设置；相反，通过-D选项在sphinx-build命令行上提供它应该更可取，如下所示

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¶

类型:: 序列[str]
默认:: ()

作为列表提供给 latex 的附加参数。

imgmath_latex_preamble¶

类型:: str
默认:: ''

要放入用于转换数学片段的 LaTeX 文件前导码中的额外 LaTeX 代码。例如，用于添加修改数学所用字体的包，如无衬线字体的'\\usepackage{newtxsf}'，或衬线字体的'\\usepackage{fouriernc}'。事实上，默认的 LaTeX 数学字体字符较细，在 HTML 输出中通常与文本字体不匹配。

imgmath_dvipng¶

类型:: str
默认:: 'dvipng'

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

imgmath_dvipng_args¶

类型:: 序列[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¶

类型:: 序列[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以加载旧版本，或更新您的配置选项。通常，MathJax v3 和 v4 选项是兼容的。

版本 1.1 新增。

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

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

注意

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

提示

MathJax 配置可以通过使用mathjax_config_path选项在 JavaScript 文件中提供。这对于更复杂的配置（例如 JavaScript 函数）非常有用，这些配置很难仅使用 Python 字典表达。

mathjax_path¶

类型:: str
默认:: 'https://cdn.jsdelivr.net.cn/npm/mathjax@4/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。

版本 4.0 中的变化: MathJax 的默认版本现在是版本 3。要继续使用 MathJax v2，您必须通过此选项显式加载它。例如

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

版本 9.0 中的变化: MathJax 的默认版本现在是版本 4。要继续使用 MathJax v3，您必须通过此选项显式加载它。例如

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

mathjax_options¶

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

mathjax 的脚本标签选项。例如，您可以通过以下设置设置 integrity 选项

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

版本 1.8 中新增。

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

mathjax4_config¶

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

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

有关将旧 MathJax 配置转换为新的mathjax4_config的帮助，请参阅将旧配置转换为 v4。

在版本 9.0 中新增。

mathjax3_config¶

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

MathJax v3（可以通过mathjax_path加载）的配置选项。如果给定，字典将转换为 JSON 对象并分配给 JavaScript 变量window.MathJax。

有关更多信息，请阅读配置 MathJax。

4.0 版本新增。

mathjax2_config¶

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

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

例如

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

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

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

mathjax_config¶

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

mathjax2_config的旧名称。

版本 1.8 中新增。

版本 4.0 中的变化: 这已重命名为mathjax2_config。mathjax_config仍然支持以实现向后兼容。

mathjax_config_path¶

类型:: str
默认:: ''

如果给定，这必须是 JavaScript (.js) 文件（相对于配置目录的路径）的路径，其中包含 MathJax 的配置选项。示例

mathjax_config_path = 'mathjax-config.js'

重要

用户有责任确保给定文件与正在使用的 MathJax 版本兼容。

有关更多信息，请阅读配置 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 安装在共享位置。

Sphinx HTML 输出的数学支持¶

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

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

sphinxcontrib.jsmath – 通过 JavaScript 渲染数学¶

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

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

`sphinxcontrib.jsmath` – 通过 JavaScript 渲染数学¶