Python Sphinx多同名结构模块文档生成冲突问题：无需修改代码导入的解决方法问询

你的问题核心在于Python模块查找机制的优先级冲突：当你把foo和bar的根目录都加到sys.path后，Sphinx会优先加载第一个路径（foo）里的src模块，后续同名的src（来自bar）会被完全忽略，导致最终文档只显示其中一套模块的内容。

下面提供两种无需修改代码导入语句的解决方案，你可以根据实际场景选择：

方法一：动态切换环境+清除模块缓存（无需额外文件） #

这种方法通过在不同文档章节中临时调整sys.path并清除已加载的模块缓存，让Sphinx分别处理foo和bar的src模块。

1. 为foo和bar分别创建独立的文档文件，比如foo_modules.rst和bar_modules.rst：

   • foo_modules.rst：

     .. code-block:: python
        :hidden:
     
        import sys, os, importlib
     
        # 清除已加载的src相关模块，避免缓存干扰
        for mod_name in list(sys.modules.keys()):
            if mod_name.startswith('src'):
                del sys.modules[mod_name]
     
        # 调整sys.path，确保foo的路径优先级最高
        foo_root = os.path.abspath('../../folder/foo/')
        bar_root = os.path.abspath('../../folder/bar/')
        sys.path = [foo_root] + [p for p in sys.path if p != bar_root]
     
        # 导入目标模块（可选，确保Sphinx能找到）
        import src.folder1.fileA
        import src.folder1.fileB
     
     ## Foo项目模块文档
     .. automodule:: src.folder1.fileA
        :members:
     .. automodule:: src.folder1.fileB
        :members:
     

   • bar_modules.rst：

     .. code-block:: python
        :hidden:
     
        import sys, os, importlib
     
        # 清除已加载的src相关模块，避免缓存干扰
        for mod_name in list(sys.modules.keys()):
            if mod_name.startswith('src'):
                del sys.modules[mod_name]
     
        # 调整sys.path，确保bar的路径优先级最高
        bar_root = os.path.abspath('../../folder/bar/')
        foo_root = os.path.abspath('../../folder/foo/')
        sys.path = [bar_root] + [p for p in sys.path if p != foo_root]
     
        # 导入目标模块（可选，确保Sphinx能找到）
        import src.folder1.fileA
        import src.folder1.fileB
     
     ## Bar项目模块文档
     .. automodule:: src.folder1.fileA
        :members:
     .. automodule:: src.folder1.fileB
        :members:
     

2. 在主文档（比如index.rst）中引入这两个文件：

   .. toctree::
      :maxdepth: 2
      :caption: 项目文档
   
      foo_modules
      bar_modules
   

方法二：使用命名空间包（更优雅，需添加空文件） #

这种方法通过让foo和bar成为命名空间包，让Sphinx可以通过完整路径区分两个src模块，无需频繁切换环境。

1. 在foo和bar的根目录下各添加一个空的__init__.py文件（不影响原有代码的运行逻辑）：

   folder
   ├── foo
   │   ├── __init__.py  # 新增空文件
   │   └── src
   │       └── ...
   └── bar
       ├── __init__.py  # 新增空文件
       └── src
           └── ...
   

2. 修改conf.py中的sys.path配置，只把folder目录加入路径：

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

3. 在文档中使用完整的命名空间路径引用模块：

   ## Foo项目模块文档
   .. automodule:: foo.src.folder1.fileA
      :members:
   .. automodule:: foo.src.folder1.fileB
      :members:
   
   ## Bar项目模块文档
   .. automodule:: bar.src.folder1.fileA
      :members:
   .. automodule:: bar.src.folder1.fileB
      :members:
   

两种方法都能解决你的问题：如果完全不想修改任何文件，选方法一；如果可以接受添加两个空的__init__.py，方法二更简洁稳定。

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