Sphinx中的HTML输出的数学支持¶

Added in version 0.5.

在 1.8 版本发生变更: 非HTML构建器的数学支持已集成到sphinx-core中.因此不再需要mathbase扩展.

由于数学符号在HTML中并没有得到本地支持,Sphinx为HTML文档提供了多个扩展的数学支持.这些扩展使用了reStructuredText数学 指令 和 角色 .

`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 and dvisvgm both have the ability to collect from LaTeX the “depth” of the rendered math: an inline image should use this “depth” in a vertical-align style to get correctly aligned with surrounding text.

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

在 2.2 版本发生变更: 此选项可以与 'svg' imgmath_image_format 一起使用.

imgmath_add_tooltips¶: 默认:True .如果为假,则不将 LaTeX 代码添加为数学图像的 “alt” 属性.

imgmath_font_size¶: 显示数学公式的字体大小（单位:”pt”）.默认值为”12”.必须是正整数.

imgmath_latex¶

用于调用LaTeX的命令名称.默认值为 'latex' ;如果 latex 不在可执行文件搜索路径中,您可能需要将其设置为完整路径.

由于此设置在系统之间不可移植,因此通常在 conf.py 中设置它并没有太大用处;相反,最好通过 :program :sphinx-build 命令行中的 -D 选项来给它,例如:

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

此值应仅包含latex可执行文件的路径,而不应包括其他参数;使用 imgmath_latex_args 来达到这个目的.

提示

要通过自定义 imgmath_latex_preamble 使用 unicode-math 的 OpenType Math fonts,您可以将 imgmath_latex 设置为 'dvilualatex' ,但必须将 imgmath_image_format 设置为 'svg' . 注意:这仅在 dvisvgm 3.0.3 中进行了测试.与使用标准 'latex' 和传统 TeX 数学字体相比,这显著增加了图像生成的时间.

提示

一些花哨的LaTeX标记（一个例子使用TikZ为方程添加各种装饰）需要多次运行LaTeX可执行文件.为此,请将此配置设置为 'latexmk' （或其完整路径）,因为这个Perl脚本能够可靠地动态选择所需的LaTeX运行次数.

在 6.2.0 版本发生变更: 现在支持使用 'xelatex' （或其完整路径）.但您必须将 '-no-pdf' 添加到命令选项的:confval: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 . 如果为真,則在 HTML 文件中编码 LaTeX 输出图像（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文件中.然后加载JavaScript包MathJax,实时将LaTeX标记转换为浏览器可读的数学公式.

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

注意

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

mathjax_path¶

在HTML文件中包含的JavaScript文件的路径,以加载MathJax.

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

路径可以是绝对的或相对的;如果是相对的,则是相对于构建文档的 _static 目录.

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

您也可以提供一个与CDN URL不同的完整 https:// URL.

mathjax_options¶

用于mathjax的script标签选项.例如,您可以通过以下设置来设置完整性选项:

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

默认是空的 ( {} ).

Added in version 1.8.

在 4.4.1 版本发生变更: 允许在设置了 “async “或 “defer “键的情况下更改 MathJax 的加载方式（异步或延迟）.

mathjax3_config¶

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

默认值为空（未配置）.

Added in version 4.0.

mathjax2_config¶

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

例如:

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配置转换为新的:confval:mathjax3_config 的帮助,请参见将您的v2配置转换为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安装在共享位置.

Sphinx中的HTML输出的数学支持¶

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

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

sphinx.ext.jsmath – 通过JavaScript渲染数学公式¶

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

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

`sphinx.ext.jsmath` – 通过JavaScript渲染数学公式¶