如何在Jupyter Notebook中引用Sphinx生成的API文档章节？

直接写rst源文件相对路径报“文件未找到”是两个核心原因：

• Notebook存放在/docs/notebooks子目录，Sphinx构建时不会自动将普通Markdown相对链接映射到上级目录的rst源文件，且最终发布产物是html文件，直接链接.rst源文件本身不符合Sphinx的链接解析逻辑
• autodoc自动生成的API文档锚点不是手动写的#mymod.modname，是Sphinx按固定规则生成的，手动写的锚点无法匹配

方案1：使用Sphinx原生交叉引用（推荐，无路径维护成本） #

Sphinx解析Notebook依赖的nbsphinx扩展原生支持在Markdown单元格中直接使用rst角色语法，和普通rst文件的写法完全一致，不需要手动配置路径：
在Notebook的Markdown单元格中直接写入：

See also the :py:mod:`mypkg.modname` documentation.

构建后会自动生成指向对应模块API文档的可跳转链接，后续调整目录结构时只要模块名不变，链接就不会失效。

方案2：使用标准Markdown链接格式 #

如果必须用Markdown原生的[链接文本](路径)格式，按以下步骤配置：

1. 在Sphinx配置文件conf.py中添加配置，让nbsphinx按html产物路径解析普通链接：

nbsphinx_link_target = "html"

2. 在Notebook中写链接时，路径指向构建后的html文件，使用Sphinx生成的标准模块锚点：

[查看modname模块API文档](../mypkg.mymod.html#module-mypkg.modname)

说明：路径前缀../对应构建后Notebook html存放在_build/html/notebooks子目录、根文档html存放在_build/html目录的层级关系；锚点前缀module-是Sphinx autodoc生成模块文档时的固定前缀，不要自行修改。

异常排查 #

如果配置后仍无法跳转，优先检查两项配置：

• 确认conf.py的extensions列表中已添加nbsphinx，且顺序排在sphinx.ext.autodoc之后
• 确认自动生成的mypkg.mymod.rst已经被加入到toctree索引中，没有被Sphinx排除在构建范围外

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