如何实现多个Sphinx项目共享含reStructuredText文件的目录？

你的问题出在include路径的相对位置错误：conf.py位于client1/source目录下，你设置的./shared是相对于该目录的路径，实际指向client1/source/shared（不存在），而真正的shared目录在my_project根目录下，和client1同级。

• 修正conf.py中的搜索路径
  打开client1/source/conf.py，添加共享目录到Sphinx的文件搜索路径中。因为从client1/source到shared需要向上两级目录，所以使用相对路径的绝对化写法：

  import os
  import sys
  # 将shared目录添加到搜索路径
  sys.path.insert(0, os.path.abspath('../../shared'))
  

• 在toctree中直接引用共享文档
  修改client1/source/index.rst的toctree，直接写共享文件的文件名即可，无需额外路径：

  .. toctree::
     :maxdepth: 2
     :caption: 文档目录
  
     file1
     file2
  

• 新增client的复用方案
  未来新增client目录时，只需在对应client的source/conf.py中复制上述路径配置代码，即可直接在其index.rst的toctree中引用shared下的文档，无需修改路径。

注意事项：

• 确保shared目录下的.rst文件没有重复的文档名称（避免和client自身的文档冲突）
• 如果shared中的文档需要引用其他共享文件，路径也需基于shared目录自身的相对位置来写

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