Sphinx autosummary报failed to import Child.model 无法识别继承实例属性

该警告是Sphinx 4.3.0版本autosummary功能的已知局限性导致的：autosummary做静态代码扫描时，默认只会识别类直接定义的类属性，不会主动遍历父类的__init__方法提取继承的实例属性，因此找不到Child从Base继承来的model属性，抛出导入失败警告。

• 方案1：修改Sphinx配置文件conf.py，开启继承成员的自动识别
  向conf.py中添加以下配置项：

  # 开启自动继承父类成员
  autodoc_default_options = {
      "inherited-members": True,
      "undoc-members": True
  }
  # 开启文档字符串继承
  autodoc_inherit_docstrings = True
  # 确保autosummary自动生成文档
  autosummary_generate = True
  

  改完后执行make clean html重新构建即可。

• 方案2：修改Python代码，将实例属性提前声明为类属性
  把父类中定义在__init__里的实例属性移到类级别声明，方便Sphinx静态扫描识别，不需要修改原有初始化逻辑：

  class Base:
      """Base class."""
      model = None
      """An attribute."""
  
      def __init__(self, **kwargs):
          """Init."""
          pass
  

  该方法兼容性最好，也符合Python类型注解的通用规范。

• 方案3：屏蔽对应警告（仅适用于不需要在子类文档中展示该继承属性的场景）
  如果你不需要在Child类的文档里展示继承来的model属性，可以在conf.py中添加配置直接屏蔽该警告：

  suppress_warnings = ["autosummary.import"]
  

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