Sphinx中对HTML输出的数学支持

0.5 新版功能.

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

由于HTML本身不支持数学符号，因此Sphinx为具有多个扩展的HTML文档提供了数学支持。

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

1.4 新版功能.

This extension renders math via LaTeX and dvipng or dvisvgm into PNG or SVG images. This of course means that the computer where the docs are built must have both programs available.

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

imgmath_image_format

The output image format. The default is 'png'. It should be either 'png' or 'svg'.

imgmath_latex

The command name with which to invoke LaTeX. The default is 'latex'; you may need to set this to a full path if latex is not in the executable search path.

Since this setting is not portable from system to system, it is normally not useful to set it in conf.py; rather, giving it on the sphinx-build command line via the -D option should be preferable, like this:

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

This value should only contain the path to the latex executable, not further arguments; use imgmath_latex_args for that purpose.

imgmath_dvipng

The command name with which to invoke dvipng. The default is 'dvipng'; you may need to set this to a full path if dvipng is not in the executable search path. This option is only used when imgmath_image_format is set to 'png'.

imgmath_dvisvgm

The command name with which to invoke dvisvgm. The default is 'dvisvgm'; you may need to set this to a full path if dvisvgm is not in the executable search path. This option is only used when imgmath_image_format is 'svg'.

imgmath_latex_args

Additional arguments to give to latex, as a list. The default is an empty list.

imgmath_latex_preamble

Additional LaTeX code to put into the preamble of the short LaTeX files that are used to translate the math snippets. This is empty by default. Use it e.g. to add more packages whose commands you want to use in the math.

imgmath_dvipng_args

Additional arguments to give to dvipng, as a list. The default value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'] which makes the image a bit darker and larger then it is by default, and produces PNGs with a transparent background. This option is used only when imgmath_image_format is 'png'.

imgmath_dvisvgm_args

Additional arguments to give to dvisvgm, as a list. The default value is ['--no-fonts']. This option is used only when imgmath_image_format is 'svg'.

imgmath_use_preview

dvipng has the ability to determine the “depth” of the rendered text: for example, when typesetting a fraction inline, the baseline of surrounding text should not be flush with the bottom of the image, rather the image should extend a bit below the baseline. This is what TeX calls “depth”. When this is enabled, the images put into the HTML document will get a vertical-align style that correctly aligns the baselines.

Unfortunately, this only works when the preview-latex package is installed. Therefore, the default for this option is False.

Currently this option is only used when imgmath_image_format is 'png'.

imgmath_add_tooltips

Default: True. If false, do not add the LaTeX code as an “alt” attribute for math images.

imgmath_font_size

The font size (in pt) of the displayed math. The default value is 12. It must be a positive integer.

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

1.1 新版功能.

This extension puts math as-is into the HTML files. The JavaScript package MathJax is then loaded and transforms the LaTeX markup to readable math live in the browser.

Because MathJax (and the necessary fonts) is very large, it is not included in Sphinx.

mathjax_path

The path to the JavaScript file to include in the HTML files in order to load MathJax.

The default is the https:// URL that loads the JS files from the cdnjs Content Delivery Network. See the MathJax Getting Started page for details. If you want MathJax to be available offline, you have to download it and set this value to a different path.

The path can be absolute or relative; if it is relative, it is relative to the _static directory of the built docs.

For example, if you put MathJax into the static path of the Sphinx docs, this value would be MathJax/MathJax.js. If you host more than one Sphinx documentation set on one server, it is advisable to install MathJax in a shared location.

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

mathjax_options

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

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

默认为空 ({}).

mathjax_config

mathjax的内联配置选项。该值用作 MathJax.Hub.Config（） 的参数。 有关更多信息，请阅读 Using in-line configuration options 。

例如:

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

默认值为空（未配置）。

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

此扩展名与MathJax扩展名一样，但使用较旧的包 jsMath 。它提供此配置值:

jsmath_path

要包含在HTML文件中以加载JSMath的JavaScript文件的路径。没有默认值。

The path can be absolute or relative; if it is relative, it is relative to the _static directory of the built docs.

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