Sphinx生成pkg_app模块文档遇模块找不到的正确配置方案

问题背景 #

项目结构如下：

• project_name/pkg_app：存放Python源码模块及__init__.py
• project_name/sphinx_documentation：Sphinx文档生成目录，包含conf.py、index.rst等配置文件

使用不引用Python源码的.rst文件生成HTML文档时一切正常，但给pkg_app.rst添加automodule指令后，执行make html会出现警告：WARNING: autodoc: failed to import module 'pkg_app'

解决步骤 #

1. 修改conf.py的路径配置
   将conf.py中的sys.path设置修改为：

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

该配置让Sphinx能够找到上级目录中的pkg_app模块。

2. 配置pkg_app.rst文件
   使用以下内容配置pkg_app.rst，即可生成所有模块的文档：

源代码文档
=========================

pkg_app目录包含__init__.py、models.py、forms.py和routes.py文件

模块内容
---------------

.. automodule:: pkg_app
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: pkg_app.models
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: pkg_app.forms
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: pkg_app.routes
   :members:
   :undoc-members:
   :show-inheritance:

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