如何配置Sphinx autodoc提取Python DocString并展示在HTML中

现有配置的核心问题 #

• 模块导入路径配置错误：当前sys.path.insert(0, os.path.abspath('.'))指向conf.py所在的文档目录，没有把项目源码根目录加入Python导入路径，autodoc无法找到目标Python模块
• 扩展列表重复声明了两次sphinx.ext.autodoc，属于冗余配置
• 缺少autodoc默认规则配置，且未确认包结构合规，容易漏抓成员文档
• 若存在多层子模块，单条automodule指令默认不会递归抓取所有子模块内容

分步配置流程 #

1. 修正conf.py配置 #

首先调整Python导入路径，不要用依赖执行目录的相对路径，基于conf.py自身位置拼接源码根目录路径，避免路径识别错误：

import os
import sys
# conf.py一般存放在项目的docs目录下，上一级即为项目根目录（存放Python源码包的层级）
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

清理重复的扩展声明，补充常用autodoc默认配置，添加到General configuration区块即可：

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.coverage",
]

# autodoc默认抓取规则
autodoc_default_options = {
    "members": True, # 自动提取所有公开类、函数、方法
    "undoc-members": True, # 展示未写docstring的成员，不需要可设为False
    "show-inheritance": True, # 展示类的继承关系
    "special-members": "__init__", # 提取类初始化方法的docstring
    # 若需要提取单下划线开头的私有成员，取消下一行注释
    # "private-members": True,
}

注意：执行sphinx构建命令时，必须使用安装了项目所有依赖的Python环境，否则导入模块时会因依赖缺失失败，导致docstring无法提取

2. 确认Python包结构合规 #

所有需要被autodoc识别的Python包目录下，必须存在空的或包含内容的__init__.py文件，否则Python不会将该目录识别为可导入模块，autodoc无法抓取内容。
标准项目目录结构参考：

项目根目录/
├── trying_sphinx/          # 业务源码包
│   ├── __init__.py         # 必须存在
│   └── src.py              # 业务代码文件
└── docs/                   # Sphinx文档目录
    ├── conf.py
    ├── index.rst
    ├── _static/
    └── _templates/

3. 配置rst文档引用 #

如果项目存在多层子模块，不要手动写单条automodule指令，直接在docs目录下执行以下命令，自动扫描所有源码模块生成对应的rst引用文件：

sphinx-apidoc -o . ../trying_sphinx

执行完成后会生成modules.rst、对应各子模块的rst文件，将生成的入口文件加入index.rst的toctree列表，确保内容会被渲染到HTML中：

Welcome to Trying-Sphinx's documentation!
=========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search'

如果是单文件模块，可直接保留automodule写法，确保模块路径和Python导入路径完全一致即可。

4. 重新构建文档 #

每次修改配置或源码后，先清理旧的构建缓存再重新生成HTML，避免旧内容干扰：

make clean
make html

如果构建过程中出现ImportError报错，优先检查sys.path配置的路径层级是否正确，可在conf.py中加print(sys.path)打印路径列表，确认源码根目录确实在导入路径中，且在对应Python环境下可正常执行import trying_sphinx.src不报错。

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