如何在Sphinx中交叉引用PlantUML图？

要实现PlantUML图的numref交叉引用且不保存导出图片，核心思路是用原生figure指令包裹PlantUML代码——因为numref是针对Sphinx原生figure标签设计的，直接给uml指令加标签不被支持。

步骤1：配置PlantUML生成临时图片 #

在项目的conf.py中设置PlantUML的缓存目录，让生成的图片仅存于构建目录（不会提交到仓库）：

extensions = ['sphinxcontrib.plantuml']
# 替换为你的PlantUML实际执行路径
plantuml = 'java -jar /usr/local/bin/plantuml.jar'
plantuml_output_format = 'svg'  # 可根据需求选择png/svg等格式
# 指定临时缓存目录，建议将此目录加入.gitignore
plantuml_cache_path = '_build/plantuml_cache'

步骤2：用figure包裹PlantUML代码 #

在RST文档中，把uml指令嵌套在figure块内，给figure添加:label:属性：

.. figure::
   :label: diag
   :align: center

   .. uml::
      :caption: 示例PlantUML交互流程
      
      @startuml
      Alice -> Bob: 发送请求
      Bob --> Alice: 返回响应
      @enduml

步骤3：正常使用numref引用 #

现在就可以用:numref:diag``在文本中引用这张图，系统会自动按文档顺序生成带编号的格式（比如Fig. 1）。

关键说明 #

• 直接给uml指令加:label:无效，因为sphinxcontrib-plantuml扩展的uml指令未实现标签注册逻辑，而figure是Sphinx原生支持标签和自动编号的容器。
• 务必将_build/plantuml_cache加入.gitignore，避免临时图片文件被提交到代码仓库。

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