Sphinx自定义指令中嵌套引用的实现问题求助

问题重现 #

在为Sphinx自定义指令添加嵌套引用支持时，基于todo示例改写代码后，使用嵌套的:ref:foo reference``触发如下错误：

preparing documents... done
/home/martyn/work/sphinx_example/someotherfile.rst:6: WARNING: unknown node type: <pending_xref: <inline...>>

Exception occurred:
File "/home/martyn/.local/lib/python3.10/site-packages/docutils/nodes.py", line 2040, in unknown_departure
raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.html5.HTML5Translator'> departing unknown node type: pending_xref

错误根源 #

问题出在process_todo_nodes方法的事件绑定时机：

• 绑定到doctree-resolved事件时，Sphinx已完成文档树的最终解析，此时用于解析引用的上下文状态（如环境变量中的引用映射、文档上下文）已失效。
• 嵌套解析生成的pending_xref节点无法被后续流程处理，导致HTML翻译阶段遇到未知节点，触发异常。

解决方案 #

方案1：调整事件绑定时机（推荐） #

将process_todo_nodes的绑定事件从doctree-resolved改为更早的doctree-read阶段。这个阶段文档树刚生成，引用解析所需的状态完全有效，嵌套解析后的pending_xref节点能被Sphinx默认引用处理流程正常识别和解析。

修改事件注册代码：

# 替换原有的doctree-resolved绑定
app.connect('doctree-read', process_todo_nodes)

方案2：手动传递解析上下文（适用于必须在doctree-resolved阶段处理的场景） #

如果必须在doctree-resolved阶段处理节点，需在嵌套解析时手动传递当前文档的环境对象（env），确保解析器能获取到引用解析所需的状态：

# 在process_todo_nodes中调用嵌套解析时，传入env参数
nested_parser.parse(content, document, env=env)

同时确保解析后的节点能被正确整合到文档树中，完成pending_xref节点的解析流程。

验证 #

修改后重新执行文档构建命令，嵌套的:ref引用应能正常解析，不再出现pending_xref相关的警告和异常。

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