如何在reStructuredText中设置网格表格的标题、宽度及PDF跨页

一、带自动编号的表格标题设置 #

要实现带自动编号的表格标题，需将网格表格嵌套在table指令内，同时确保Sphinx配置开启表格编号功能：

• 在conf.py中添加或确认配置：

  numfig = True
  numfig_format = {'table': 'Table %s'}
  

• 正确的嵌套写法：

  .. table:: Specifications
     :widths: 3, 11
     :class: longtable
  
     .. tabularcolumns:: |m{3cm}|m{11cm}|
     .. grid-table::
        :header-rows: 1
  
        * - 列1标题
          - 列2标题
        * - 内容1
          - 长内容示例...
        * - 跨列合并示例
          - :rspan: 2 此处为跨两行的内容
        * - 内容2
          - 
        * - 内容3
          - 
  

  table指令的标题会自动生成编号，grid-table负责实现列合并需求。

二、自定义表格宽度 #

有两种方式可自定义表格宽度，按需选择：

• 固定宽度：通过tabularcolumns指定每列具体宽度，如|m{3cm}|m{11cm}|，适合需要精确控制列宽的场景。
• 比例宽度：使用table指令的:widths:参数设置列宽比例，如:widths: 3, 11表示两列宽度占比为3:11，会根据页面宽度自动适配。

三、PDF跨页显示实现 #

要让长表格在PDF中跨页，需满足以下条件：

1. 确保longtable类正确绑定在table指令上，且你的PDF生成后端（如LaTeX）支持longtable包。
2. 在conf.py的LaTeX配置中加载longtable包：

   latex_elements = {
       'preamble': r'\usepackage{longtable}',
   }
   

3. 避免表格前出现强制分页或过多空内容，确保表格长度足够触发自动跨页逻辑。

注意：单独使用grid-table时，标题和longtable类不会生效，必须将grid-table嵌套在table指令内部才能继承这些属性。

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