如何在自定义Sphinx扩展中调用sphinx-tabs指令？

错误原因分析 #

你直接调用TabDirective.run(self)时，传入的是自身的指令实例，而TabDirective本身要求包含内容块（has_content=True），但你的指令设置了has_content=False，导致Tab指令尝试读取内容时触发错误。直接调用第三方指令的run方法确实不规范，因为指令依赖自身的上下文（参数、内容、解析环境等），强行复用自己的上下文必然会引发冲突。

正确解决方案：直接构造sphinx-tabs的节点树 #

Sphinx的指令最终都会生成对应的文档节点树，与其调用第三方指令的run方法，不如直接构造sphinx_tabs对应的节点，这种方式更可靠且符合Sphinx的扩展规范。

步骤1：导入sphinx-tabs的节点类 #

首先从sphinx_tabs中导入它定义的标签页节点：

from sphinx_tabs.tabs import TabsNode, TabNode

步骤2：构造标签页节点并添加你的代码块 #

基于你已有的asm_raw_node，构造完整的标签页结构：

# 创建最外层的tabs容器节点
tabs_container = TabsNode()

# 创建第一个标签页，设置标题
raw_asm_tab = TabNode(title="原始汇编")
# 将你生成的汇编代码块节点添加到该标签页的子节点中
raw_asm_tab.children.append(asm_raw_node)
# 把标签页添加到容器中
tabs_container.children.append(raw_asm_tab)

# 如果需要多个标签页，重复上述步骤即可
# 示例：添加编译列表输出标签页
# list_output_node = nodes.literal_block(list_output, list_output)
# list_output_node["language"] = "text"
# list_tab = TabNode(title="编译列表输出")
# list_tab.children.append(list_output_node)
# tabs_container.children.append(list_tab)

# 最后返回包含tabs容器的节点列表
return [tabs_container]

补充说明 #

• 这种方式绕过了指令的上下文依赖，完全通过节点构造实现需求，不会出现内容块缺失的错误。
• 若后续sphinx_tabs版本更新导致节点类名或结构变化，可以查看其源码（通常在sphinx_tabs/tabs.py中）确认最新的节点定义。

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