sphinx-plantuml 简介
PlantUML 是可以用纯文本语言绘制图表的开源软件. PlantUML 支持许多统一建模语言, 也支持其他软件开发相关的格式, 比如 C4 模型/电脑网络图/ER 模型/甘特图/心智图和工作分解结构图等, 也可以用在 JSON 及 YAML 文档的可视化.
在 Sphinx 中, 你可以使用 sphinx-contrib/plantuml 在文档中插入 PlantUML 图片. 但是构建环境需要配置 Java 以及 PlantUML 相关 jar 包, 配置起来比较麻烦. 此外, 本地编译也比较慢, 拖慢整个构建过程.
因此我开发了 sphinx-plantuml 库, sphinx-plantuml 的优点有:
纯 Python 库, 无需配置任何环境或者依赖, 开箱即用.
快速的构建速度, 因为构建过程无需编译 PlantUML.
兼容内置
figure
命令大部分参数, 容易上手.支持
.uml
文件的引用, 便于项目管理.
sphinx-plantuml 原理
sphinx-plantuml 工作原理如 图 1 所示.
sphinx-plantuml 利用 https://plantuml.com 网站对 PlantUML 代码进行渲染. 构建的时候不需要渲染, 也不需要联网. 只有在文档被浏览时才会渲染, 因此浏览的时候需要联网. 由于是利用官方网站进行渲染, 因此构建环境无需配置 PlantUML 相关依赖.
sphinx-plantuml 安装
使用 python3 -m pip install sphinx-plantuml
安装 sphinx-plantuml.
然后在你的 conf.py
文件中添加插件的引用, 如下代码所示.
extensions = [
...
'sphinxcontrib.plantuml',
...
]
sphinx-plantuml 使用
sphinx-plantuml 提供了 plantuml
命令. 你可以直接在 plantuml
中写 UML 语言, 比如 列表 1 所示的 reST 代码.
.. plantuml::
:align: center
@startuml
Alice -> Bob: test
@enduml
其渲染结果如下图所示.
sphinx-plantuml 默认将图片渲染成 .svg
, 如果你想渲染成 .png
, 可以使用 :format:
参数指定渲染格式, 比如 列表 2 所示的 reST 代码.
.. plantuml::
:align: center
:format: png
@startuml
Alice -> Bob: test
@enduml
其渲染结果如下图所示.
如果你想给图片添加标题, 可以使用 :caption:
参数指定标题, 如 列表 3 所示的 reST 代码.
.. plantuml::
:align: center
:format: png
:caption: 苟利国家生死以, 岂因祸福避趋之
@startuml
Alice -> Bob: test
@enduml
其渲染结果如下图所示.
Sphinx 内置的 figure
命令的大部分参数 plantuml
都支持, 比如你可以使用 :width:
参数来设置图片的大小, 如 列表 4 所示.
.. plantuml::
:align: center
:format: png
:width: 50%
@startuml
Alice -> Bob: test
@enduml
其渲染结果如下图所示.
备注
不是所有的 figure
的参数都支持, 因为无法提前获取图片的尺寸, :scale:
参数就无法支持.
如果你的 PlantUML 代码是在另一个文件中, 可以采用如 列表 5 所示代码实现.
.. plantuml:: /umls/insert_html.uml
:align: center
:width: 50%
:caption: 内嵌 HTML 示例
.. plantuml:: /umls/aws_demo.uml
:align: center
:width: 50%
:caption: AWS 示例
.. plantuml:: /umls/c4_demo.uml
:caption: C4 模型示例
:format: svg
:width: 50%
:align: center
列表 5 中的代码的渲染效果如下所示.
其中三个 .uml
文件的下载链接如下: