Sphinx(reStructuredText)智能表格扩展及flat-table实现方法咨询

可用的高效表格扩展 #

针对RST下需要频繁做单元格合并、拆分的复杂表格场景，目前可用性最高的方案是支持flat-table语法的扩展：

• 不需要像原生grid table那样手动对齐每一列的网格线，用列表结构就能写表格，编写门槛低
• 原生支持跨行、跨列合并属性，不需要额外hack样式
• 和Sphinx等常用RST渲染工具适配度高，输出样式稳定
  其余可选方案包括增强版list-table、支持外部导入的csv-table，但这类扩展对合并单元格的支持普遍不完善，只适合简单规则表格使用。

flat-table合并单元格代码调整方法 #

你当前代码无法输出预期合并效果，核心是没搞对flat-table的合并规则，规则非常简单：

• 跨行用:rspan:n`标记，n代表当前单元格向下额外占的行数，不含当前行。比如一个单元格要纵向总共占3行，n填2即可
• 跨列用:cspan:n`标记，n代表当前单元格向右额外占的列数，不含当前列
• 所有被跨行、跨列覆盖的位置，不需要再写对应的单元格条目，多写就会出现列错位、内容溢出的问题

对应你要做的BLE badge特征表，修正后可直接渲染出预期效果的代码如下：

.. flat-table:: Characteristics of the BLE badge
   :header-rows: 1

   * - Col 1
     - Col 2
     - Col 3
   * - :rspan:`2` 0xfee7
     - 0xfec7
     - WRITE
   * - 0xfec8
     - INDICATE
   * - 0xfec9
     - READ
   * - 0xfee0
     - 0xfee1
     - NOTIFY, READ, WRITE

如果需要调整最后一部分的合并效果，比如让0xfee0纵向跨行，只需要给它加上对应数值的:rspan:标记，同时删掉后续被覆盖行对应列的单元格条目即可，写法和前面的0xfee7完全一致。

如果日常需要批量写这类表格，可以先在可视化表格编辑器里整理好内容和合并关系，再通过简单的文本替换批量转成flat-table语法，不需要逐行手动编写。

内容的提问来源于stack exchange，提问作者Sushivam