Plantuml 文件未包含在第一个文档中

Question

首先考虑以下几点：

.. uml:: ClassDiagram.puml
   :caption: ClassDiagram

conf.py 仅包含扩展名：

extensions = ["sphinxcontrib.plantuml"]

使用 Sphinx，我构建了一个 html 页面。 包含的uml图如下：

此图像是使用输入作为文件名生成的，而不是文件名的内容。

我做错了什么？

我找不到任何关于此问题的现有问题。

Python版本：3.12.3

狮身人面像版本：7.2.6

Answer 1

我认为您是说 UML 图呈现文字文本“ClassDiagram.puml”，而不是同名文件中的 content。 我无法重现这个问题。 您的最小可重现示例不显示Sphinx构建日志，或文件内容

ClassDiagram.puml

。

PlantUML 对其接受的内容很自由，因此您可以省略很多内容 - 例如

@startuml

@enduml

标签 - 并且它仍然可以解析/渲染。 无论我传递隐式文件名还是显式 UML 脚本，Sphinx 扩展 似乎都能正确区分参数。 所以...

.. uml::
    :caption: MyExample

    ClassDiagram.puml

将渲染得很好，就像（实时服务器演示）。

.. uml:: ClassDiagram.puml
    :caption: MyExample

将渲染该文件的内容如果文件存在，或者失败

WARNING: PlantUML file "ClassDiagram.puml" cannot be read: [Errno 2] No such file or directory

如果文件不存在。

.. uml:: ClassDiagram.puml
    :caption: MyExample

    a dummy
    UML script

会失败

WARNING: uml directive cannot have both content and a filename argument [docutils]

。

.. uml:: 
    :caption: MyExample

    a dummy
    UML script

将会失败

/home/mc1/Desktop/temp/index.rst:35: WARNING: error while running plantuml

（内容已传递给 PlantUML，但因语法无效而被拒绝）。

后续步骤...

• 您的构建日志显示什么？
• 文件

  ClassDiagram.puml

  确实存在吗？
• 将 UML 脚本从文件移入指令块是否有效？
• 有任何杂散的 文件行结尾 或不可打印的字符吗？
• 用 Kroki Sphinx 扩展代替？
• 也许您解决了问题 - 为了社区的利益请提供反馈？

.

# My environment
$ python --version
Python 3.12.3
$ sphinx-build --version
sphinx-build 8.1.3
$ find ~/venv/lib/python3.12/site-packages -iname "*plant*"
sphinxcontrib_plantuml-0.30