sphinx-autoapi设置autoapi_python_class_content='both'无法合并类与__init__文档字符串

排查与修复方案 #

• 确认配置正确性
  检查conf.py中配置项的拼写和位置，确保没有错误：

  # 启用autoapi扩展
  extensions = [
      # 其他已启用的扩展
      'autoapi.extension',
  ]
  # 设置合并类与__init__文档字符串
  autoapi_python_class_content = 'both'
  

• 检查文档字符串格式
  确保SingleOutputEcospold2Importer类和其__init__方法的文档字符串格式规范，无语法错误。示例：

  class SingleOutputEcospold2Importer:
      """类级文档：说明该导入器的核心功能与适用场景。"""
  
      def __init__(self, file_path):
          """初始化导入器实例。
  
          :param file_path: Ecospold2格式文件的路径
          :type file_path: str
          """
          self.file_path = file_path
  

  避免使用与当前文档解析器（reStructuredText/Markdown）不兼容的标记。

• 清理缓存后重新构建
  Sphinx和autoapi可能留存旧缓存，导致配置不生效，执行以下命令彻底重建：

  make clean
  make html
  

• 升级sphinx-autoapi版本
  旧版本可能存在该配置项的bug，升级到最新稳定版：

  pip install --upgrade sphinx-autoapi
  

• 验证类的定义方式
  若SingleOutputEcospold2Importer是通过装饰器、元类动态生成的，可能干扰autoapi的解析逻辑，确保类为直接定义的常规类。

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