使用nested_parse解析原始.rst文本报错，Sphinx扩展开发求助

错误原因 #

出现AttributeError: 'list' object has no attribute 'parent'的核心原因是你传递给nested_parse的父节点参数是列表，而该方法要求传入单个docutils节点对象作为解析内容的容器。

正确实现步骤 #

在自定义指令的.run()方法中，按以下流程处理：

• 将构建好的flat-table纯rst字符串转换为StringList（Sphinx/docutils处理文本输入的标准格式）
• 创建空的nodes.Element()作为父容器节点
• 使用nested_parse_with_titles（或原生nested_parse）解析文本，将结果存入父容器
• 返回父容器的子节点列表

代码示例 #

from docutils import nodes
from docutils.statemachine import StringList
from sphinx.util.nodes import nested_parse_with_titles
from sphinx.util.docutils import SphinxDirective

class MyCustomDirective(SphinxDirective):
    def run(self):
        # 构建目标flat-table的rst内容
        flat_table_rst = """
.. flat-table:: 自定义转换表格
    :header-rows: 1

    * - 表头列1
      - 表头列2
    * - 数据行1列1
      - 数据行1列2
    * - 数据行2列1
      - 数据行2列2
        """
        # 拆分字符串为行并转换为StringList
        rst_lines = StringList(flat_table_rst.strip().splitlines())
        # 创建父节点作为解析结果的容器
        parent_node = nodes.Element()
        # 解析rst内容到父节点中
        nested_parse_with_titles(self.state, rst_lines, parent_node)
        # 返回解析后的子节点列表，符合run方法的返回要求
        return parent_node.children

关键说明 #

• nested_parse_with_titles是Sphinx封装的便捷方法，相比原生nested_parse更适合处理包含指令、标题等结构的rst文本
• 必须使用单个节点对象作为父容器，绝对不能直接传递列表，这是触发错误的根本原因
• 最终返回父节点的children属性，因为.run()方法要求返回节点列表而非单个节点

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