Sphinx中对HTML输出的数学支持

Added in version 0.5.

在 1.8 版本发生变更: 对非HTML构建器的数学支持集成到了Shinx-core中。因此，不再需要数学库扩展。

由于HTML本身并不以任何方式支持数学表示法，因此Sphinx通过几个扩展为HTML文档提供了数学支持。这些函数使用reStructiredText数学 directive 和 role 。

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

Added in version 1.4.

此扩展通过LaTeX和 dvipng 或 dvisvgm 转换为PNG或SVG图像。当然，这意味着构建文档的计算机必须同时具有这两个程序。

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

imgmath_image_format
类型:
'png' | 'svg'
默认:
'png'

输出图像格式。它应为 'png' 或 'svg' .图像是通过首先执行来生成的 latex 然后在TeX数学标记上（取决于请求的格式） dvipng 或 dvisvgm .

imgmath_use_preview
类型:
bool
默认:
False

dvipng 和 dvisvgm 两者都能够从LaTeX收集所呈现数学的“深度”：内联图像应该在 vertical-align 样式以与周围文本正确对齐。

此机制需要 LaTeX preview package (提供以下形式 preview-latex-style 在Ubuntu Xenial上)。因此，此选项的缺省值为 False 但强烈建议将其设置为 True 。

在 2.2 版本发生变更: 此选项可与 'svg' imgmath_image_format 。

imgmath_add_tooltips
类型:
bool
默认:
True

如果为假，请勿将LaTeX代码添加为数学图像的“alt”属性。

imgmath_font_size
类型:
int
默认:
12

字体大小（以 pt ）。这必须是正整数。

imgmath_latex
类型:
str
默认:
'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
类型:
Sequence[str]
默认:
()

列出乳胶的其他论点。

imgmath_latex_preamble
类型:
str
默认:
''

Additional LaTeX code to put into the preamble of the LaTeX files used to translate the math snippets. Use it e.g. to add packages which modify the fonts used for math, such as '\\usepackage{newtxsf}' for sans-serif fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed, the default LaTeX math fonts have rather thin glyphs which (in HTML output) often do not match well with the font for text.

imgmath_dvipng
类型:
str
默认:
'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
类型:
str
默认:
'dvisvgm'

要调用的命令名 dvisvgm .如果出现以下情况，您可能需要将其设置为完整路径 dvisvgm 不在可执行搜索路径中。此选项仅在以下情况下使用 imgmath_image_format 是 'svg' .

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

作为列表提供给dvisvGM的其他论点。默认值意味着 dvisvgm 将字形渲染为路径元素（参见 dvisvgm FAQ ).此选项仅在以下情况下使用 imgmath_image_format 是 'svg' .

imgmath_embed
类型:
bool
默认:
False

如果为真，请将LaTeX输出图像编码到HTML文件（base64编码）中，并且不要将单独的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文件中。该Java程序包 MathJax 然后加载并将LaTeX标记转换为浏览器中实时可读的数学。

因为MathJax(和必要的字体)非常大，所以它不包括在Sphinx中，但被设置为从第三方站点自动包括它。

注意

你应该运用数学方法 directive 和 role ，而不是本地的MathJax $$ ， \( 等

mathjax_path
类型:
str
默认:
'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

要包含在用于加载MathJax的HTML文件中的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
类型:
dict[str, Any]
默认:
{}

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

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

Added in version 1.8.

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

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

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

Added in version 4.0.

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

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
类型:
dict[str, Any] | None
默认:
None

原名： 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
类型:
str
默认:
''

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

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

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