解决Sphinx基于两个独立sys.path生成文档时的同名子目录模块识别冲突问题

我完全理解你碰到的这个头疼问题——当feature和extract这两个独立目录下存在同名子模块时，Sphinx的autodoc会因为sys.path的优先级顺序，直接取第一个匹配的模块，导致另一个目录下的同名模块文档无法正确生成。既然修改目录名不是可行选项，咱们可以试试这几个更稳妥的解决方案：

方案一：使用绝对模块路径指定目标（最推荐） #

核心思路就是在所有rst文档里，明确指定模块的完整绝对路径，让Sphinx不用再猜该找哪个目录下的模块。

1. 调整toctree条目
   比如修改feature/modules.rst里的toctree，把每个子模块改成完整的包路径：

   feature
   =======
   
   .. toctree::
      :maxdepth: 3
   
      feature.app_package
      feature.call_logs
      feature.contact_list
      feature.sms_logs
      feature.user
   

   对应的extract/modules.rst也要改成：

   extract
   =======
   
   .. toctree::
      :maxdepth: 3
   
      extract.app_packages
      extract.call_logs
      extract.contact_list
      extract.sms_logs
      extract.user
      extract.users
   

2. 修改autodoc指令
   在每个子模块对应的rst文件（比如call_logs.rst）里，也要用完整的绝对路径指定模块：

   # feature下的call_logs文档
   .. automodule:: feature.call_logs
      :members:
      :undoc-members:
   

   # extract下的call_logs文档
   .. automodule:: extract.call_logs
      :members:
      :undoc-members:
   

这样不管sys.path里的顺序如何，Sphinx都能精准定位到对应的模块，彻底解决冲突。

方案二：简化sys.path，统一用顶层包路径导入 #

如果你的项目结构里，feature和extract都是feature_service的子目录，那可以简化conf.py里的sys.path配置，只添加feature_service的父目录，然后所有模块都通过顶层包来引用。

1. 修改conf.py的sys.path
   把原来的多条路径改成只加顶层目录：

   sys.path.insert(0, os.path.abspath('../../'))  # 指向feature_service的父目录
   

2. 使用完整的顶层包路径
   之后所有模块引用都写成feature_service.feature.call_logs和feature_service.extract.call_logs的形式，比如toctree条目和autodoc指令都用这个完整路径。这种方式更符合Python的包导入规范，也能从根源避免路径冲突。

额外注意事项 #

• 确保每个目录下都有__init__.py文件（Python 3.3+支持命名空间包，但显式添加该文件能让Sphinx更稳定地识别包结构）。
• 每次修改配置后，记得删除Sphinx的_build缓存目录，再重新构建文档，避免缓存导致的旧路径残留问题。

备注：内容来源于stack exchange，提问作者Akshit