如何在Sphinx中复用ReStructuredText部分表格指令模板？

针对你需要复用表格通用配置和表头、仅替换数据行的需求，结合Sphinx的扩展性，提供两种实用方案：

方案一：自定义Sphinx指令（推荐） #

通过编写简单的Sphinx扩展，创建专属指令封装通用表格结构，使用时只需传入数据行即可。

1. 创建扩展文件
   在项目的conf.py同目录下新建table_ext.py，写入以下代码：

from docutils.parsers.rst import Directive
from docutils.nodes import container
from docutils.statemachine import ViewList

class ReusableTableDirective(Directive):
    has_content = True  # 允许指令接收数据行内容

    def run(self):
        # 预定义通用表格的配置和表头
        table_template = [
            '.. list-table::',
            '    :align: left',
            '    :header-rows: 1',
            '    :width: 100%',
            '    :widths: 25 25 25 25',
            '',
            '    * - ColumnHeader1',
            '      - ColumnHeader2',
            '      - ColumnHeader3',
            '      - ColumnHeader4',
        ]
        # 合并模板和用户传入的数据行
        full_content = table_template + self.content
        # 解析合并后的内容为ReStructuredText节点
        view_list = ViewList(full_content, self.content.parent.source)
        container_node = container()
        self.state.nested_parse(view_list, self.content_offset, container_node)
        return container_node.children

def setup(app):
    app.add_directive('reusable-table', ReusableTableDirective)
    return {
        'version': '0.1',
        'parallel_read_safe': True,
    }

2. 加载扩展
   在conf.py的extensions列表中添加该扩展：

extensions = [
    # 其他已有的扩展
    'table_ext'
]

3. 使用方式
   在任意.rst文件中，直接调用自定义指令并传入数据行：

.. reusable-table::
    * - 数据行1列1
      - 数据行1列2
      - 数据行1列3
      - 数据行1列4
    * - 数据行2列1
      - 数据行2列2
      - 数据行2列3
      - 数据行2列4

方案二：Jinja2模板片段 #

利用Sphinx的Jinja2模板支持，将表格模板与数据分离，适合习惯模板语法的场景。

1. 安装并启用扩展
   先安装sphinx-jinja扩展：

pip install sphinx-jinja

然后在conf.py中启用：

extensions = [
    # 其他扩展
    'sphinx_jinja'
]

2. 创建模板文件
   在项目的templates目录下新建table_header.rst.j2（如果没有templates目录，先创建并在conf.py中设置templates_path = ['templates']），写入模板内容：

.. list-table::
    :align: left
    :header-rows: 1
    :width: 100%
    :widths: 25 25 25 25

    * - ColumnHeader1
      - ColumnHeader2
      - ColumnHeader3
      - ColumnHeader4
    {% for row in data_rows %}
    * - {{ row[0] }}
      - {{ row[1] }}
      - {{ row[2] }}
      - {{ row[3] }}
    {% endfor %}

3. 在RST中调用模板
   在需要使用表格的.rst文件中，传入数据并渲染模板：

.. jinja:: default
    :file: table_header.rst.j2
    :context:
        data_rows = [
            ("数据1-1", "数据1-2", "数据1-3", "数据1-4"),
            ("数据2-1", "数据2-2", "数据2-3", "数据2-4"),
        ]

两种方案中，自定义指令更贴合ReStructuredText的书写习惯，不需要额外学习模板语法，是更推荐的选择。

内容的提问来源于stack exchange，提问作者André Keller