Sphinx如何让自动生成的函数文档显示完整信息？

你按照Sphinx自动文档生成教程完成配置后，Python文件lumache的文档被自动生成到api.rst，但目前仅展示函数名称及文档字符串首行，希望能像使用.. autofunction::那样显示函数的参数、返回值及完整文档字符串，可按以下步骤操作：

1. 确认Sphinx扩展配置 #

确保conf.py中已启用核心扩展，这是提取详细信息的基础：

extensions = [
    'sphinx.ext.autodoc',  # 必选，自动提取文档内容
    'sphinx.ext.napoleon'  # 可选，支持Google/NumPy风格文档字符串解析
    # 其他已启用的扩展...
]

2. 修改api.rst的自动生成指令 #

默认自动生成的.. automodule::指令缺少显示控制选项，修改为：

.. automodule:: lumache
   :members:               # 显示模块内所有带文档的成员
   :undoc-members:         # 可选，显示无文档字符串的成员
   :show-inheritance:      # 可选，显示类的继承关系（如果有类）
   :member-order: bysource # 按代码中的顺序展示成员，而非默认字母序

3. 规范函数的文档字符串格式 #

确保文档字符串包含参数、返回值的清晰说明，两种常用格式示例：

• reStructuredText风格（无需额外扩展）：

  def get_random_ingredients(kind=None):
      """
      返回随机食材字符串列表。
  
      :param kind: 可选的食材类型
      :type kind: str or None
      :return: 随机食材列表
      :rtype: list[str]
      """
      # 函数实现代码
  

• Google风格（需启用sphinx.ext.napoleon）：

  def get_random_ingredients(kind=None):
      """
      返回随机食材字符串列表。
  
      Args:
          kind (str, optional): 可选的食材类型
  
      Returns:
          list[str]: 随机食材列表
      """
      # 函数实现代码
  

4. 重新构建文档 #

执行构建命令更新文档：

# Linux/macOS环境
make html

# Windows环境
.\make.bat html

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