如何修复Sphinx扩展中两个Builder生成不同文档树的问题？

这问题我之前处理过类似的，核心是你大概率在自定义指令阶段就根据不同Builder生成了不一样的文档树节点，导致两个Builder的文档结构出现差异。正确的做法是统一文档树节点，把不同Builder的渲染逻辑分离到各自的节点访问器中，具体步骤如下：

1. 定义统一的自定义文档树节点 #

先创建一个通用的自定义节点类，不管用哪个Builder处理，指令生成的都是这个节点，确保文档树结构完全一致：

from docutils import nodes

class TestActionNode(nodes.Element):
    """自定义节点，用于承载test_action指令的内容"""
    pass

2. 修改test_action指令，只生成统一节点 #

把原来指令中直接生成表格/div的逻辑移除，只创建TestActionNode并把指令内容存入节点属性，让后续Builder来处理具体渲染：

from docutils.parsers.rst import Directive

class TestActionDirective(Directive):
    required_arguments = 0
    optional_arguments = 0
    has_content = True

    def run(self):
        # 创建统一的自定义节点
        action_node = TestActionNode()
        # 将指令的原始内容存入节点属性，供后续渲染逻辑调用
        action_node["raw_content"] = "\n".join(self.content)
        return [action_node]

3. 给HTML Builder注册节点渲染逻辑 #

为默认HTML Builder添加TestActionNode的访问器，在这里实现转成HTML表格的逻辑：

def visit_test_action_html(self, node):
    # 开始生成表格标签（可自定义class样式）
    self.body.append('<table class="test-action-table">')
    # 根据节点属性填充表格内容（可根据需求调整表格结构）
    self.body.append(f'<tr><td>{node["raw_content"]}</td></tr>')

def depart_test_action_html(self, node):
    # 闭合表格标签
    self.body.append('</table>')

4. 给xmlexport Builder注册节点渲染逻辑 #

为你的自定义xmlexport Builder添加对应的访问器，实现仅用div包裹内容的逻辑：

def visit_test_action_xmlexport(self, node):
    # 开始div标签（可自定义class）
    self.output.append('<div class="test-action-wrapper">')
    # 直接输出原始内容，不做额外转换
    self.output.append(node["raw_content"])

def depart_test_action_xmlexport(self, node):
    # 闭合div标签
    self.output.append('</div>')

5. 在setup函数中完成注册绑定 #

最后在扩展的setup函数里，把自定义节点、指令和对应Builder的访问器绑定起来：

def setup(app):
    # 注册自定义指令
    app.add_directive("test_action", TestActionDirective)
    # 注册自定义节点，并为不同Builder绑定对应的访问器
    app.add_node(
        TestActionNode,
        html=(visit_test_action_html, depart_test_action_html),
        xmlexport=(visit_test_action_xmlexport, depart_test_action_xmlexport)
    )
    return {
        'version': '0.1',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

为什么这样能解决问题？ #

原来的问题根源在于你可能在指令处理阶段就根据当前Builder生成了不同的节点（比如HTML Builder生成表格节点，xmlexport生成div节点），导致两个Builder的文档树结构不一致。现在我们让指令只生成同一个自定义节点，把不同Builder的渲染逻辑完全分离到各自的访问器中，这样不管用哪个Builder，文档树的结构都是一致的，只是最终输出的内容不同，完美符合你的需求。

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