Sphinx启用sphinx.ext.autodoc时无法识别docstring的Parameters/Returns段

你当前编写的带Parameters/Returns分节、短横线做分隔的docstring是NumPy风格格式，原生sphinx.ext.autodoc仅支持reStructuredText原生格式的docstring解析，没有内置这类结构化分节docstring的解析规则，因此这部分内容无法被识别为参数、返回值模块，只会被当做普通文本处理甚至排版错乱。

优先用官方扩展适配，无需改动现有docstring内容：

• 修改Sphinx项目的conf.py配置文件，在extensions列表中添加Sphinx内置的Napoleon扩展（Sphinx 1.3及以上版本自带，无需额外安装）：

  extensions = [
      'sphinx.ext.autodoc',
      'sphinx.ext.napoleon',
      # 保留你之前已经启用的其他扩展
  ]
  

• 在conf.py中添加Napoleon的匹配配置，对齐你当前使用的NumPy风格docstring规则，避免解析冲突：

  # 关闭Google风格docstring解析，减少规则干扰
  napoleon_google_docstring = False
  # 启用NumPy风格docstring解析
  napoleon_numpy_docstring = True
  # 将Parameters块转换为Sphinx标准的param域标记
  napoleon_use_param = True
  # 将Returns块转换为Sphinx标准的returns、rtype域标记
  napoleon_use_rtype = True
  

• 清理Sphinx的旧构建缓存（删除_build目录下所有生成的旧文件），重新执行文档构建命令即可：

  # Linux/macOS
  make clean && make html
  # Windows
  make.bat clean && make.bat html
  

如果不想启用Napoleon扩展，可以把所有docstring改成Sphinx原生支持的reST格式，示例如下：

class CampaignNamingTool(models.Model):
    """
    活动命名工具（Campaign Naming Tool）旨在协助账户管理人员遵循活动命名规范，避免因命名问题引发bug或活动遗漏。由于工作流中活动名称大小写敏感，所有命名不规范、命名错误的活动都会被忽略，不会展示在用户的插入订单列表中。请使用该表单创建您的首个活动。
    
    :param user: 活动的所有者或负责人。
    :param year: 活动正式上线的年份
    :param month: 活动正式上线的月份
    :param advertiser: 活动对应的广告主。
    :param name: 活动名称。
    :param device: 活动投放的目标设备（Desktop、Mobile、tablette）。
    :param type_of_format: 活动投放的广告格式（IAB、Video、Habillage等）
    :param kpi: 活动考核KPI（CPM、CPC、CPV、CPA等）
    :return: 由上述所有参数拼接生成的Insertion Order对象
    """

这种格式不需要额外扩展就能被原生autodoc识别，但需要批量修改已有docstring，维护成本更高。

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