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 所示.

图 1 sphinx-plantuml 工作原理

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 代码.

列表 1 可以直接 plantuml 环境中写 UML 代码

.. plantuml::
    :align: center

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

图 2 列表 1 渲染效果

sphinx-plantuml 默认将图片渲染成 .svg, 如果你想渲染成 .png, 可以使用 :format: 参数指定渲染格式, 比如 列表 2 所示的 reST 代码.

列表 2 指定图片渲染格式

.. plantuml::
    :align: center
    :format: png

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

图 3 png 渲染效果

如果你想给图片添加标题, 可以使用 :caption: 参数指定标题, 如 列表 3 所示的 reST 代码.

列表 3 指定图片标题

.. plantuml::
    :align: center
    :format: png
    :caption: 苟利国家生死以, 岂因祸福避趋之

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

图 4 苟利国家生死以, 岂因祸福避趋之

Sphinx 内置的 figure 命令的大部分参数 plantuml 都支持, 比如你可以使用 :width: 参数来设置图片的大小, 如 列表 4 所示.

列表 4 指定图片宽度

.. plantuml::
    :align: center
    :format: png
    :width: 50%

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

图 5 50% 宽度的图片

备注

不是所有的 figure 的参数都支持, 因为无法提前获取图片的尺寸, :scale: 参数就无法支持.

如果你的 PlantUML 代码是在另一个文件中, 可以采用如 列表 5 所示代码实现.

列表 5 引用 PlantUML 代码文件

.. 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 中的代码的渲染效果如下所示.

图 6 内嵌 HTML 示例

图 7 AWS 示例

图 8 C4 模型示例

其中三个 .uml 文件的下载链接如下:

• insert_html.uml;

• aws_demo.uml;

• c4_demo.uml.