Sphinx 基于两个独立的 sys.path 生成文档

Question

我有以下结构要呈现为文档

索引.rst：

.. toctree::
   :maxdepth: 2
   :caption: Feature Family

   feature/modules.rst



.. toctree::
   :maxdepth: 2
   :caption: Extract

   extract/modules.rst

功能/模块.rst：

feature
=======

.. toctree::
   :maxdepth: 3

   app_package
   call_logs
   contact_list
   sms_logs
   user

提取/模块.rst：

extract
=======

.. toctree::
   :maxdepth: 3

   app_packages
   call_logs
   contact_list
   sms_logs
   user
   users

现在

feature/modules.rst

和

extract/modules.rst

具有以下子类别文件夹名称：

call_logs, contact_list, sms_logs , user 

这就是为什么 sphinx 在构建相应文档时对使用哪个 sys.path 感到困惑。目前我的

conf.py

有以下定义：

sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, os.path.abspath('../../feature_service/feature'))
sys.path.insert(0, os.path.abspath('../../feature_service/extract'))

只有当我从 sys.path 中删除

../../feature_service/extract

时，

../../feature_service/feature

中的文档才会正确生成，因为这些类别下的子文件夹的名称是相同的重叠我怀疑 sphinx 混淆了在哪个目录中查看时使用

autodoc

有没有解决方法？将文件夹名称更改为不同的名称可以，但不建议

Answer 1

找到解决方案。由于子文件夹具有通用名称，我决定执行以下操作：

1. 更新 sys.path 以仅包含这些：

sys.path.insert(0, os.path.abspath('../../feature_service'))
sys.path.insert(0, os.path.abspath('../../feature_service/feature'))
## Exclude `extract` intentionally
#sys.path.insert(0, os.path.abspath('../../feature_service/extract'))

2. 更新

   extract/modules.rst

   下的子.rst文件以正确定位目录，例如添加前缀

   extract.

   ，如下所示：

.. automodule:: extract.app_packages.v0_1.extract
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: extract.app_packages.v0_1
   :members:
   :undoc-members:
   :show-inheritance: