使用Sphinx为KivyMD项目生成HTML文档时找不到png加载器如何解决

错误原因 #

该报错核心为Sphinx运行autodoc导入项目模块时，Kivy在无头命令行环境下未自动加载png格式对应的图片加载器，KivyMD初始化主题组件时读取内部png资源失败，导致模块导入中断。

可行解决方案 #

方案一：预配置Kivy无头环境（适合需要动态执行代码生成文档的场景） #

打开Sphinx项目目录下的source/conf.py文件，在文件最开头添加如下配置代码：

import os
# 配置Kivy无头运行模式
os.environ['KIVY_NO_ARGS'] = '1'
os.environ['KIVY_HEADLESS'] = '1'
# 预注册PIL图片处理器，解决png加载问题
from kivy.core.image import ImageLoader
ImageLoader.register('pil')
# 提前初始化Kivy核心组件
from kivy.app import App

保存后重新执行make html命令即可正常生成文档。

方案二：Mock GUI依赖（适合仅静态解析代码注释/结构的场景） #

如果不需要实际运行KivyMD代码，仅需要解析代码结构和注释生成文档，可以直接让autodoc模拟导入所有GUI相关依赖，跳过实际加载流程。
同样在source/conf.py中添加如下配置：

# 确保已经加载autodoc扩展
extensions = [
    'sphinx.ext.autodoc',
    # 你的其他扩展
]

# 配置要模拟导入的模块
autodoc_mock_imports = [
    'kivy',
    'kivymd',
    # 其他需要mock的GUI相关依赖可继续追加
]

该方案无需初始化Kivy环境，稳定性更高，不会出现其他GUI相关的运行报错。

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