如何配置Sphinx autodoc以文档化__init__.py中的类

1. Sphinx对__init__.py文档的支持性 #

Sphinx完全支持识别__init__.py中定义的类、方法、函数的文档字符串，这是sphinx.ext.autodoc的基础能力之一，你遇到的渲染为空的问题和__init__.py本身无关。

2. 警告处理必要性 #

你遇到的No module named 'ps.xxx'; 'ps' is not a package警告必须处理。该警告表示autodoc在构建时无法导入指定模块，导入失败就无法读取模块内的任何文档内容，是生成空白HTML页面的核心原因。

3. 可行修复方案 #

核心问题是conf.py中配置的Python模块搜索路径错误：你的ps包存放在packages/pss/src/dd路径下，而当前配置仅将项目根目录加入搜索路径，Python无法从根目录直接定位到ps包。

步骤1：修正conf.py的路径配置 #

替换conf.py中原有的sys.path插入逻辑：

import os
import sys
# 将ps包所在的父目录dd加入Python搜索路径
sys.path.insert(0, os.path.abspath('../../packages/pss/src/dd'))

步骤2：（非必需，仅针对非隐式命名空间包）补全包标识 #

如果没有使用隐式命名空间包，需要在ps目录下新增空的__init__.py文件，明确将ps标识为Python可导入包。

步骤3：清理缓存重新构建 #

# 删除旧的自动生成文件和构建缓存
rm -rf source/api/*
rm -rf build/*
# 重新生成apidoc配置
sphinx-apidoc -o source/api/ ../packages/pss/src/dd/ps/ --implicit-namespaces -e -M -P
# 重新构建HTML文档
make html

可选优化 #

如果当前__all__仅配置了['Xxx']，想要XxxData类也出现在文档中，直接将XxxData加入__all__列表即可，无需修改其他Sphinx配置。

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