数学表达式渲染方式

6.1. 数学表达式渲染方式#

由于计算机在处理数学表达式的复杂性，使用Sphinx生成不同的输出结果时需要对数学表达式的渲染方式进行恰当的配置。 注意，只有在渲染成 HTML 时才需要配置；对于其他的引擎不必特意处理。

备注

Changed in version 1.8: Math support for non-HTML builders is integrated to sphinx-core. So mathbase extension is no longer needed.

在创建Sphinx工程时会询问如何处理数学表达式的:

> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y

一般推荐使用 MathJax ，不需要额外的安装配置。这也是目前 Sphinx 缺省推荐使用的方式。 最简单的方法是选择使用 MathJax （两者只能选一个），这样生成的 "conf.py" 里的 extensions 项里只有 'sphinx.ext.mathjax', 如下:

extensions = [
  ... ...
  'sphinx.ext.mathjax',
  ... ...
]

如果想更改，可以注释掉 'sphinx.ext.mathjax', ， 并添加 'sphinx.ext.imgmath', 即可.

备注

Sphinx主要通过两种方法对数学表达式进行渲染生成HTML ( 二选一 )，都需要扩展模块的支持；但是， MathJax 是缺省的方式（不必配置就可以使用）。

  • 'sphinx.ext.mathjax' : 通过 MathJax 渲染 。

  • 'sphinx.ext.imgmath' : 通过 LaTex 渲染成图片( png 或 svg ) 。

6.1.1. 添加插件#

首先，要在 conf.py 中添加数学引擎，如:

# conf.py
extensions = [
    'sphinx.ext.mathjax',
]

然后，我们就可以在 html 里面编写基于 LaTeX 的数学表达式了，行间数学表达式格式如下：

.. math::
    # write the math code here

6.1.2. 使用MathJax渲染公式#

MathJax （ 官方文档 ）是一个 JavaScript 数学表达式渲染引擎。在使用 Sphinx 将 reStructuredText 文档转换为 HTML 后，往往需要用 MathJax 来支持其中的数学表达式输出。

如上所述, 使用MathJax (准确说是Render math via JavaScript) 渲染公式, 需要在 extensions 列表变量里添加项 'sphinx.ext.mathjax', .

# 向 extensions 变量中添加一项 'sphinx.ext.mathjax'
extensions = ['sphinx.ext.mathjax', ...]

此外, 你还需要配置MathJax的路径 mathjax_path , Sphinx默认使用 MathJax CDN 提供的 JS 文件。 Sphinx默认使用的MathJax的路径值为 https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML 。 但在某些情况下可能无法使用， 可能是 https 安全协议的问题, 改成 http 即可, 即设置配置文件 conf.py 中的

mathjax_path = 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

当然你也可以使用本地的MathJax, 参考 Installing Your Own Copy of MathJax , 到 mathjax/MathJax 下载MathJax包 (约34.1MB) 并解压放到 "_static" 目录, 然后设置路径, 即在 conf.py 文件中添加代码:

::

mathjax_path = MathJax/MathJax.js

更多细节问题请参考 Math support in Sphinx .

警告

由于 reStructuredText 与 MathJax 语法的兼容性，Sphinx 并非接受 MathJax 的所有功能。 MathJax 的自动编号在 Sphinx 文档中很难进行交叉引用，因此仍然推荐使用 Sphinx 的 :label: 角色。

同理，在 reStructuredText 文档中，应当使用 :math: 行内角色，而不是 MathJax 支持的 $..$ 语法。

在 conf.py 中，我们还可能需要配置 mathjax_config 变量来设置 MathJax，比如启用 MathJax 支持的 公式自动编号 ：

# 如果是 MathJax v2，使用：
# mathjax2_config = {
#    'TeX': {
#        'equationNumbers': { 'autoNumber': "AMS" }
#    }
# }
mathjax3_config = {
    'tex': {'tags': 'ams'}
}

6.1.3. 使用LaTex渲染公式#

如上所述, 在 extensions 列表变量里添加项 'sphinx.ext.imgmath', 即可。 数学表达式通过LaTex引擎渲染成图片, 然后在HTML中显示. 但要求PC机安装有LaTex.

如果你不使用默认配置, 请参考 Math support in Sphinx .

6.1.4. 使用KaTex渲染公式#

KaTex 具有比 MathJax更快的解析速度。 使用 pip install sphinxcontrib.katex 安装 KaTex 扩展。 如上所述, 在 extensions 列表变量里添加项 'sphinxcontrib.katex', 即可。 数学表达式通过KaTex引擎渲染公式在HTML中显示。

警告

2024年测试尚不稳定。会有一些冲突。生成结果的显示也存在有问题。

6.1.5. 自定义数学命令#

MathJax 允许自定义简单的 LaTeX 命令，即 LaTeX 中的 \newcommand 命令。

警告

一般情况下不建议自定义 Latex 命令，在使用下面介绍的案例时产生的冲突，生成的结果出现很多的问题；而且没有必要。 除非是特殊的情况，例如以数学表达式为主的文档。

在 Sphinx 中，由于 rst_prolog 变量的存在，我们可以直接在 conf.py 文件中更改该变量值来在每一个文档文件的头部添加一个额外的数学环境，用于自定义数学命令：

rst_prolog = """
.. math::

   \\newcommand{\\ud}{\\mathop{}\\negthinspace\mathrm{d}}
   \\newcommand{\\pfrac}[2][x]{\\frac{\\partial #2}{\\partial #1}}

.. |section-symbols| replace::
   ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
"""

上例是本文档使用的 conf.py 文件的一部分，定义了两个数学命令：

一个是 \ud 命令，无输入参数，用来打印一个竖直的积分符号。

另一个是 \pfrac[#1]{#2} 命令，有分子分母两个参数，用来打印偏导分式。参数1是分母，默认值是x；参数2是分子。

下面是一个使用了上述两个自定义符号的例子：

.. math::

    \pfrac{f(x,y)} &= y \\
    \pfrac[y]{f(x,y)} &= \int_0^\pi \sin x \ud x

因为本项目中按如上配置存在问题，效果就不演示了。

目录