Sphinx中HTML输出的数学支持

Added in version 0.5.

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

由于HTML在任何方面都不支持数学表示法，Sphinx为HTML文档提供了数学支持，并提供了几个扩展名。这些方法使用了RestructedText数学：rst:方向：directive 1`和：rst:角色：`role 2。

：模式：sphinx.ext.imgmath–将数学渲染为图像

Added in version 1.4.

这个插件通过LaTeX和dvipng或dvisvgm将数学呈现为PNG或SVG图像。这当然意味着生成文档的计算机必须同时具有这两个程序。

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

imgmath_image_format

输出图像格式。默认值为“png”。它应该是“png”或“svg”。首先对TeX数学标记执行“latex”，然后（取决于请求的格式）执行“dvipng”或“dvisvgm”来生成图像。

imgmath_use_preview

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

此机制需要“LaTeX preview包”（在Ubuntu xenial上作为“preview LaTeX style”提供）。因此，此选项的默认值为“False”，但强烈建议将其设置为“True”。

在 2.2 版本发生变更: 此选项可与“svg”一起使用：confval:imgmath_image_format。

imgmath_add_tooltips

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

imgmath_font_size

显示数学的字体大小（以“pt”为单位）。默认值为“12”。它必须是正整数。

imgmath_latex

调用LaTeX的命令名。默认值为“latex”；如果“latex”不在可执行搜索路径中，则可能需要将其设置为完整路径。

由于此设置在系统之间不可移植，因此通常设置它是没有用的``配置文件``；相反，在：program:sphinxbuild`命令行中通过：option:-D`选项给出它应该更可取，如下所示：

sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build

此值只应包含指向latex可执行文件的路径，而不应包含其他参数；为此，请使用：confval:`imgmath_latex_args’。

提示

To use `OpenType Math fonts`__ with unicode-math, via a custom imgmath_latex_preamble, you can set imgmath_latex to 'dvilualatex', but must then set imgmath_image_format to 'svg'. Note: this has only been tested with dvisvgm 3.0.3. It significantly increases image production duration compared to using standard 'latex' with traditional TeX math fonts.

提示

一些花哨的LaTeX标记（有一个例子是使用TikZ为等式添加各种装饰）需要多次运行LaTeX可执行文件。要处理此问题，请将此配置设置设置为“latexmk”（或指向它的完整路径），因为此Perl脚本可以可靠地动态选择所需的latex运行次数。

在 6.2.0 版本发生变更: Using 'xelatex' (or a full path to it) is now supported. But you must then add '-no-pdf' to the imgmath_latex_args list of the command options. The 'svg' imgmath_image_format is required. Also, you may need the dvisvgm binary to be relatively recent (testing was done only with its 3.0.3 release).

备注

Regarding the previous note, it is currently not supported to use latexmk with option -xelatex.

imgmath_latex_args

提供给latex的其他参数，如列表。默认为空列表。

imgmath_latex_preamble

附加的LaTeX代码放入用于翻译数学片段的LaTeX文件的序言中。默认情况下为空。例如，添加修改用于数学的字体的包，如sans-serif字体的“\usepackage{newtxsf}”，或serif字体的“\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的其他参数。默认值为“[”–无字体’]`”，这意味着“dvisvgm”将把glyph呈现为路径元素（参见“dvisvgm FAQ`”）。此选项仅在“imgmath_image_format”为“svg”时使用。

imgmath_embed

Default: False. If true, encode LaTeX output images within HTML files (base64 encoded) and do not save separate png/svg files to disk.

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_x，并在浏览器中将LaTeX标记转换为可读的math live。

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

注意

你应该使用数学：rst:方向：directive 1`和：rst:角色`（`$jax，not``jax`，not``本机`。

mathjax_path

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

默认值是从“jsdeliver”内容传递网络加载JS文件的“https://”URL。有关详细信息，请参阅“MathJax入门页”。如果您希望MathJax可以脱机使用，或者不包含来自第三方站点的资源，则必须下载它并将该值设置为其他路径。

路径可以是绝对路径，也可以是相对路径；如果是相对路径，则路径是相对于生成文档的“静态”目录。

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

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

mathjax_options

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

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

默认值为空（{}`）。

Added in version 1.8.

在 4.4.1 版本发生变更: Allow to change the loading method (async or defer) of MathJax if “async” or “defer” key is set.

mathjax3_config

The configuration options for MathJax v3 (which is used by default). The given dictionary is assigned to the JavaScript variable window.MathJax. For more information, please read `Configuring MathJax`__.

默认值为空（未配置）。

Added in version 4.0.

mathjax2_config

The configuration options for MathJax v2 (which can be loaded via mathjax_path). The value is used as a parameter of 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 has been renamed to mathjax2_config.

mathjax_config

Former name of mathjax2_config.

For help converting your old MathJax configuration to to the new mathjax3_config, see `Converting Your v2 Configuration to v3`__.

Added in version 1.8.

在 4.0 版本发生变更: This has been renamed to mathjax2_config. mathjax_config is still supported for backwards compatibility.

：模式：sphinx.ext.jsmath–通过JavaScript呈现数学

此插件的工作方式与MathJax扩展相同，但使用旧的jsMath包。它提供以下配置值：

jsmath_path

要包含在HTML文件中以加载JSMath的JavaScript文件的路径。没有违约。

路径可以是绝对路径，也可以是相对路径；如果是相对路径，则路径是相对于生成文档的“静态”目录。

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