如何配置Sphinx+nbsphinx处理docs目录外的.ipynb笔记本？

核心配置调整 #

要让nbsphinx识别doc目录外的.ipynb文件，关键修改Sphinx的conf.py配置，让它能定位到外部文件：

• 添加外部目录到Sphinx路径：
  在conf.py开头插入代码，将examples目录的相对路径（假设examples与doc同级）加入Python路径：

  import os
  import sys
  sys.path.insert(0, os.path.abspath('../examples'))
  

• 指定nbsphinx的输入目录：
  在conf.py中配置nbsphinx_input_dir，明确.ipynb文件的存放位置：

  nbsphinx_input_dir = os.path.abspath('../examples')
  

文档引用路径修改 #

在.rst文档中引用外部.ipynb时，调整路径写法：

原本doc内引用写.. nbsphinx:: example_notebook.ipynb，现在改成.. nbsphinx:: ../examples/example_notebook.ipynb；如果已经配置了nbsphinx_input_dir，直接写.. nbsphinx:: example_notebook.ipynb即可。

额外注意点 #

• 检查examples目录下.ipynb文件的内部引用，比如图片、数据文件的相对路径要同步调整，避免加载失败
• 执行sphinx-build时，确保工作目录在doc下，或通过-c参数指定配置文件路径，防止路径解析出错

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