渲染数学公式¶

使用数学符号和公式的最简单方法是用 Sphinx 本身的指令：

例如上标的效果，使用 sub 表示平方等符号：

语法如下：

I\ :sup:`2`\ C

效果如： I²C

添加插件¶

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

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

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

行间公式

行间公式格式

.. math::
    # write the math code here

行内公式¶

行内公式格式

:math:`# write the math code here`

示例

行间公式显示效果：

()¶\[f'(x) = \lim_{\triangle x \to 0} \frac{f(x + \triangle x) - f(x)}{\triangle x}\]

行内公式显示效果：

\(f'(x) = \lim_{\triangle x \to 0} \frac{f(x + \triangle x) - f(x)}{\triangle x}\)

行间公式代码：

.. math::
    f'(x) = \lim_{\triangle x \to 0} \frac{f(x + \triangle x) - f(x)}{\triangle x}

行内公式代码：

:math:`f'(x) = \lim_{\triangle x \to 0} \frac{f(x + \triangle x) - f(x)}{\triangle x}`

Sphinx 常见问题及解决方式¶

部分常用的 reStructuredText 标记

引用：         [1]_            .. [1]
脚注：         [#f1]_          .. [#f1]
强制换行：     | string
Warning

在使用引用和脚注时，中括号的后面必须带至少一个空格，不然无法正常生成 html 文件。

如何固定主题 alabaster 的侧边栏

在该项目的 conf.py 下加入以下语句

html_theme_options = {
    'fixed_sidebar': True,
}

附：alabaster 主题文档地址

如何取消主页的 Page source 链接

在该项目的 conf.py 下加入以下语句

html_show_sourcelink = False 如何个性化网页图标(设置 favicon)

将目标图片 favicon.ico 放入 _static 文件夹内，然后在该项目的 conf.py 下加入以下语句

html_favicon = '_static/favicon.ico'

如何使用原始的 html 标签¶

代码：

.. raw:: html

    <hr />这里是分割线 <hr />

效果：

这里是分割线

如何支持中文搜索¶

Sphinx 默认是不支持中文搜索的。要支持中文搜索需要用到 jieba 模块。使用起来很简单。

1.安装

pip install jieba

2.使用在 conf.py 文件的最后一行加上

html_search_language = 'zh'

然后重新生成就可以了。

源： sphinx doc正式支持中文搜索啦

Sphinx数学支持¶

有关Sphinx中对数学公式的支持, 参考手册 Math support in 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 (两者只能选一个, 不信你试试) , 是的, 所以”conf.py” 里的 extensions 项里只有 'sphinx.ext.mathjax', 如下:

extensions = [
  'sphinx.ext.autodoc',
  'sphinx.ext.doctest',
  'sphinx.ext.intersphinx',
  'sphinx.ext.todo',
  'sphinx.ext.coverage',
  'sphinx.ext.mathjax',
  'sphinx.ext.ifconfig',
  'sphinx.ext.viewcode',
  'sphinx.ext.githubpages',
]

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

Note

Sphinx提供了两种数学公式的渲染方式 ( 二选一 ):

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

使用LaTex渲染公式¶

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

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

使用KaTex渲染公式¶

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

使用MathJax渲染公式¶

如上所述, 使用MathJax (准确说是Render math via JavaScript) 渲染公式, 需要在 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 , 到 https://github.com/mathjax/MathJax/archive/master.zip 下载MathJax包 (约34.1MB) 并解压放到 “_static” 目录, 然后设置路径, 即在 conf.py 文件中添加代码: mathjax_path = MathJax/MathJax.js 。

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

Sphinx文档写作管理

渲染数学公式¶

添加插件¶

行内公式¶

Sphinx 常见问题及解决方式¶

如何使用原始的 html 标签¶

如何支持中文搜索¶

Sphinx数学支持¶

使用LaTex渲染公式¶

使用KaTex渲染公式¶

使用MathJax渲染公式¶