如何在Sphinx中创建自定义req角色实现内部引用转换？

要实现输入:req:5.1 My requirement``等价于:ref:[5.1] <requirements:5.1 My requirement>`的效果，正确的做法是利用Sphinx的**延迟引用节点（pending_xref）**来处理，避免手动解析refuri/refid的问题。以下是具体实现步骤：

1. 编写自定义角色函数 #

在你的Sphinx扩展或conf.py中添加以下代码：

from docutils import nodes
from sphinx import addnodes

def req_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    # 拆分输入文本为需求编号和描述
    parts = text.split(' ', 1)
    if len(parts) != 2:
        # 格式错误处理
        msg = inliner.reporter.error(
            f"需求格式错误: {text}，请使用'编号 描述'的格式",
            line=lineno
        )
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    
    req_num, req_desc = parts
    display_text = f"[{req_num}]"
    # 构造完整的引用目标（和你的ref规则一致）
    ref_target = f"requirements:{text}"

    # 创建延迟引用节点，由Sphinx后续自动解析目标
    ref_node = addnodes.pending_xref(
        refdoc=inliner.settings.env.docname,
        reftarget=ref_target,
        reftype='ref',
        refexplicit=True,  # 显式引用（对应ref的显式文本）
        refwarn=True       # 引用不存在时触发警告
    )
    # 添加显示文本节点
    ref_node.append(nodes.Text(display_text))
    
    return [ref_node], []

2. 注册自定义角色 #

在conf.py的setup函数中注册角色：

def setup(app):
    app.add_role('req', req_role)

关键说明 #

• 为什么不用nodes.reference直接创建链接？
  在角色解析阶段，目标文档的节点可能还未生成，无法获取到目标的refid，直接创建reference节点会导致链接失效。而pending_xref是Sphinx专门用于延迟解析的节点，会在文档构建的后续阶段自动查找并绑定目标节点，正确生成有效链接。
• 确保需求文档中存在对应的标签：
  你的需求文档（如requirements.rst）中需要定义对应的引用标签，格式为：

  .. _requirements:5.1 My requirement:
  
  5.1 My requirement
  ------------------
  需求内容...
  

测试验证 #

在文档中使用:req:5.1 My requirement``，构建后会生成与:ref:[5.1] <requirements:5.1 My requirement>`完全等价的链接效果。

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