对sphinx中HTML输出的数学支持

Added in version 0.5.

在 1.8 版本发生变更: 非HTML构建器的数学支持集成到sphinx核心中。因此不再需要MathBase扩展。

由于HTML在任何方面都不支持数学符号，所以sphinx对具有多个扩展名的HTML文档提供了数学支持。它们使用 reStructuredText 数学 directive 和 role .

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

Added in version 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 preview package （可用作 preview-latex-style 在Ubuntu Xenial上）。因此，此选项的默认值为 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 为此目的。

提示

使用 OpenType Math fonts 使用 unicode-math ，通过自定义 imgmath_latex_preamble ，您可以设置 imgmath_latex 至 'dvilualatex' ，但随后必须设置 imgmath_image_format 至 'svg' 。注意：这只是测试过的 dvisvgm 3.0.3 。与使用标准图像制作时间相比，它显著增加了图像生成时间 'latex' 使用传统的TeX数学字体。

提示

一些花哨的 Latex 标记（报告了一个使用TikZ向公式中添加各种修饰的示例）需要多次运行 Latex 可执行文件。要处理此问题，请将此配置设置设置为 'latexmk' （或完整的路径）因为这个Perl脚本可以可靠地动态选择需要多少次latex运行。

在 6.2.0 版本发生变更: vbl.使用 '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 。如果为True，则在HTML文件(Base64编码)中对LaTeX输出图像进行编码，并且不要将单独的PNG/SVG文件保存到磁盘。

Added in version 5.2.

sphinx.ext.mathjax --通过javascript呈现数学

警告

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

Added in version 1.1.

此扩展名将数学原样放入HTML文件中。javascript包 MathJax 然后加载并在浏览器中将LaTex标记转换为可读的Math Live。

因为Mathjax（以及必要的字体）非常大，所以它不包含在Sphinx中，而是设置为从第三方网站自动包含它。

注意

你应该用数学 directive 和 role 不是本地的Mathjax $$ ， \( 等。

mathjax_path

要包含在HTML文件中以加载mathjax的javascript文件的路径。

缺省值为 https:// URL that loads the JS files from the jsdelivr 内容交付网络。请参阅 MathJax Getting Started page 了解更多细节。如果希望MathJax脱机可用或不包含来自第三方站点的资源，则必须下载它并将此值设置为不同的路径。

路径可以是绝对路径或相对路径；如果是相对路径，则它是相对于 _static 已生成文档的目录。

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

你也可以给一个完整的 https:// url与cdn url不同。

mathjax_options

为Mathjax编写标记脚本的选项。例如，可以使用以下设置设置完整性选项：

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

默认值为空 ({{}} ）

Added in version 1.8.

在 4.4.1 版本发生变更: 如果设置了“Async”或“Defer”键，则允许更改MathJax的加载方法(异步或延迟)。

mathjax3_config

MathJax v3的配置选项(默认使用)。给出的字典被赋值给JavaScript变量 window.MathJax. For more information, please read Configuring MathJax.

默认值为空（未配置）。

Added in version 4.0.

mathjax2_config

MathJax v2的配置选项(可以通过以下方式加载 mathjax_path )。该值用作的参数 MathJax.Hub.Config(). For more information, please read Using in-line configuration options.

例如：：

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

默认值为空（未配置）。

Added in version 4.0: mathjax_config 已重命名为 mathjax2_config 。

mathjax_config

原名： mathjax2_config 。

有关将旧MathJax配置转换为新配置的帮助 mathjax3_config ，见 Converting Your v2 Configuration to v3.

Added in version 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。