Sphinx reStructuredText根目录外相对路径无法识别问题：AWS CodeBuild部署时触发unknown document error

我之前也碰到过一模一样的坑——Sphinx的:doc:指令默认只认你指定的source目录（也就是docs/source）下的文档，直接引用外部目录的文件会触发内置的路径限制，你之前加的sys.path其实没用，因为sys.path是给Python模块导入用的，和Sphinx查找rst文档的逻辑完全不搭边。

给你几个可行的解决方案，按稳妥程度排序：

方案1：用:include:+内部虚拟文件绕开限制 #

这是最省心的方法，不需要改太多配置，还能完美兼容AWS CodeBuild的环境：

1. 在你的docs/source目录下新建一个空的rst文件，比如input_lambda_readme.rst
2. 在这个文件里用:include:指令引入外部的README：

   .. include:: ../../src/lambda_functions/input/README.rst
   

3. 回到你原来的文档，把:doc:的引用改成指向这个内部文件：

   * input 支持输入摄取管道。更多详情请参阅:doc:`input Lambda functions <input_lambda_readme>` - README。
   

这样Sphinx会把外部的README内容嵌入到内部的虚拟文件中，:doc:就能正常识别了，而且只要AWS CodeBuild能访问到上级目录的文件，就不会再报错。

方案2：把外部目录加入Sphinx的源树 #

如果你想直接引用外部文件，得让Sphinx把那个目录当成自己的源树一部分：

1. 修改conf.py，计算出外部目录的绝对路径，确保它不被Sphinx排除，同时配置必要的参数：

   import os
   import sys
   
   # 获取当前conf.py所在的目录（docs/source）
   source_dir = os.path.dirname(os.path.abspath(__file__))
   # 项目根目录
   root_dir = os.path.abspath(os.path.join(source_dir, '..', '..'))
   # 外部文档所在的目录
   lambda_input_dir = os.path.join(root_dir, 'src', 'lambda_functions', 'input')
   
   # 将外部目录添加到Sphinx的搜索路径
   sys.path.insert(0, lambda_input_dir)
   
   # 确保Sphinx扫描这个目录下的.rst文件（不要排除）
   exclude_patterns = []
   # 指定Sphinx识别的文档后缀
   source_suffix = '.rst'
   

2. 之后你可以直接用:doc:引用外部的README，路径直接写文件名就行：

   :doc:`input Lambda functions <README>`
   

不过这个方法在AWS CodeBuild中需要确保构建环境允许Sphinx访问上级目录，有些严格的权限设置可能会出问题，所以方案1更稳妥。

方案3：核对AWS CodeBuild的目录结构 #

最后要确认下CodeBuild的工作目录：有时候CodeBuild拉取代码后的目录结构和你本地不一样，比如可能把代码放在了不同的子目录下，导致你的相对路径失效。可以在CodeBuild的构建脚本里加一句pwd和ls -R来打印目录结构，核对docs/source和src的相对位置是否和本地一致。

内容的提问来源于stack exchange，提问作者Andreas L.