Sphinx中plantuml扩展仅生成文件名而非UML图内容问题排查

• 文件路径不正确：ClassDiagram.puml的路径未被Sphinx正确识别。如果puml文件不在当前rst文件的同级目录，需要填写正确的相对路径；若放在项目特定目录，可在conf.py中通过plantuml_include_path配置查找路径。

• PlantUML执行环境未配置：sphinxcontrib.plantuml依赖本地PlantUML环境（需Java运行时和plantuml.jar），且必须在conf.py中指定执行命令。示例配置：

  plantuml = 'java -jar /your/path/to/plantuml.jar'
  

  未配置此项时，Sphinx无法解析puml文件，仅会显示文件名占位。

• 指令语法兼容问题：部分环境下.. uml::别名可能存在兼容问题，可尝试替换为标准指令.. plantuml:: ClassDiagram.puml。

• puml文件内容无效：若ClassDiagram.puml本身存在语法错误，Sphinx解析失败后会显示文件名。可直接用PlantUML工具打开该文件，验证是否能正常生成UML图。

• 依赖包未正确安装：确保sphinxcontrib-plantuml已安装且版本与Sphinx 7.2.6兼容。可通过pip install --upgrade sphinxcontrib-plantuml重新安装适配版本。

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