使用Sphinx 6.2.1生成Python项目文档时Docstring无法生成的问题

核心问题分析 #

你的code目录与Python内置的code模块重名，导致Sphinx尝试导入时优先匹配了内置模块，而非你的自定义包——这是报错'code' is not a package的根本原因。同时，默认的autodoc配置未开启完整成员展示，导致仅显示类和函数名，无法解析Docstring。

分步解决方案 #

1. 重命名冲突的包目录 #

将根目录下的code文件夹重命名为不与Python内置模块冲突的名称，比如mycode或src。

2. 修正conf.py的路径与配置 #

打开docs/conf.py，修改路径导入为更可靠的相对路径写法，并补充autodoc展示规则：

import os
import sys
# 从conf.py所在目录向上一级定位项目根目录
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']
# 配置autodoc默认展示所有成员及Docstring
autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'undoc-members': True,
    'show-inheritance': True
}

3. 重新生成apidoc文件 #

在项目根目录执行以下命令（替换mycode为你重命名后的目录名）：

sphinx-apidoc -o docs mycode/

该命令会生成新的mycode.rst和modules.rst，确保模块引用路径完全匹配重命名后的包。

4. 验证index.rst配置 #

保持docs/index.rst的toctree配置不变，确保包含modules条目：

Welcome to test's documentation!
================================

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

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

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

5. 测试并生成文档 #

• 先在项目根目录打开Python终端，执行import mycode.classifiers，确认模块能正常导入无报错。
• 进入docs目录执行生成命令：

cd docs
make html

额外注意事项 #

• 确保Python文件中的Docstring符合napoleon扩展支持的格式（Google或NumPy风格），否则无法被正确解析。
• 如果仍有内容未显示，检查生成的mycode.rst中每个automodule块是否包含:members:等选项，缺失则手动补充。

内容的提问来源于stack exchange，提问作者M. Merida-Floriano