Sphinx自定义指令中如何正确添加引用？

问题背景 #

为pydata-sphinx-theme开发自定义指令，用于生成内置组件列表，要求兼容多构建器、不使用raw指令。核心代码在列表项中直接添加nodes.reference节点时，触发Sphinx构建错误：

Exception occurred:
  File "/.../sphinx/writers/html5.py", line 225, in visit_reference
    assert len(node) == 1 and isinstance(node[0], nodes.image)
AssertionError

错误原因 #

Sphinx的HTML5 Writer处理reference节点时，会根据父节点类型分支：

• 若父节点是TextElement（如paragraph），按普通文本链接处理；
• 若父节点不是TextElement（如直接放在list_item下），则判定为图像引用，断言reference内部仅包含一个image节点，而我们的reference是文本内容，因此触发断言失败。

解决方案 #

将reference节点和后续文本包裹到paragraph节点（TextElement子类）中，再将paragraph作为list_item的子节点，让HTML5 Writer按普通链接处理。

修改后的核心代码 #

def run(self) -> List[nodes.Node]:
    """Create the list."""
    
    # ... 原有获取components、urls、docs的逻辑保持不变

    # 构建组件列表
    items = []
    for component, url, doc in zip(components, urls, docs):
        # 创建段落节点，统一包裹链接和描述文本
        para = nodes.paragraph()
        # 添加组件名称链接
        para += nodes.reference("", component.name, refuri=url)
        # 添加组件描述文本
        para += nodes.Text(f": {doc}")
        # 将段落作为列表项内容
        items.append(nodes.list_item("", para))

    return [nodes.bullet_list("", *items)]

效果说明 #

修改后，reference的父节点变为paragraph（TextElement），HTML5 Writer会正常渲染文本链接，同时保持文档结构合规，兼容其他构建器。

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