sphinx-excel 简介

Sphinx 插入表格有几种方式, 这几种方式都不令人满意.

因此我开发了 sphinx-excel, 可以非常方便的将 excel 文件渲染在 Sphinx 页面中, 并且支持单元格合并以及环境嵌套.

sphinx-excel 安装

可以使用 Bash 1 中命令安装 sphinx-excel.

Bash 1 安装 sphinx-excel

$ python3 -m pip install sphinx-excel

Hint

点此下载 本文当中使用的 excel 文件.

首先在 conf.py 文件中添加如下配置.

extensions = [
    'sphinxcontrib.excel',
]

然后就可以使用 excel 命令来渲染 excel 表格了, 如 Listing 1 的结果如 Table 1 所示.

Listing 1 渲染 excel 文件

.. excel:: ./tables.xlsx

excel 默认会渲染指定 excel 中的第一个 sheet, 并会把第一个 sheet 的名称显示在表格的标题, 如果你不想显示标题, 可以使用 :no-caption 参数, 如 Listing 2 所示.

Listing 2 渲染 excel 文件, 不显示标题

.. excel:: ./tables.xlsx
   :no-caption:

如果想使用其他标题, 可以使用 :caption: 参数指定标题, 如 Listing 3 所示.

Listing 3 渲染 excel 文件, 指定标题

.. excel:: ./tables.xlsx
   :caption: 优秀员工

excel 兼容 Sphinx 内置 table 命令的所有参数, 比如, 可以使用 :align: 使表格居中显示, 如 Listing 4 所示.

Listing 4 渲染 excel 文件, 居中显示

.. excel:: ./tables.xlsx
   :align: center

如果一个 excel 中有多个 sheet, 可以使用 :sheet: 参数来指定渲染哪个 sheet, 如 Listing 5 所示.

Listing 5 渲染 excel 文件, 指定 sheet

.. excel:: ./tables.xlsx
   :align: center
   :sheet: 员工信息

值得注意的是, excel 默认会将第一行加粗, 表示该行是表头, 如果表头行数不为 1, 需要使用 :headers: 参数指定, 如 Listing 6 所示.

Listing 6 渲染 excel 文件, 指定表头行数

.. excel:: ./tables.xlsx
   :align: center
   :sheet: 复杂表头
   :headers: 2

excel 命令支持合并单元格的渲染, 并且支持环境嵌套, 如 Listing 7 所示, 其渲染结果如 Table 6 所示.

Listing 7 渲染 excel 文件, 合并单元格

.. excel:: ./tables.xlsx
   :align: center
   :sheet: 合并单元格
   :headers: 0

Table 6 合并单元格
Listing 8 代码示例 def add(x, y): """ return sum of x + y """ return x + y	点击 Enter 按键	显示如右所示列表	床前明月光疑是地上霜举头望明月低头思故乡
	他说苟利国家生死以, 岂因祸福避趋之.


	\(\frac{1}{1^2} + \frac{1}{2^2} + \frac{1}{3^2} + \frac{1}{4^2} + \frac{1}{5^2} + \frac{1}{6^2} + \frac{1}{7^2} + \cdots = \sum_{i=1}^\infty \frac{1}{i^2} = \frac{\pi}{6}\)

从 Table 6 中可以看出表格里可以有任何命令, 可以有代码块, 可以有 :admonition:, 可以有列表, 也可以有公式. 甚至, 代码块是可以被引用的, 如 Listing 8 所示.