使用PlantUML绘图

6.3. 使用PlantUML绘图#

PlantUML是一个开源的工具，主要用于快速创建各种UML（统一建模语言）图形，包括但不限于类图、时序图、用例图、活动图等。 它使用简单的文本描述语言来定义图形，然后可以将这些文本转换为高质量的图形图像。

6.3.1. 安装#

要启用PlantUML绘图需要两方面的安装： 一是在操作系统中安装PlantUML绘图工具，二是安装Sphinx的扩展以允许在Sphinx中调用PlantUML绘图功能。

在 Debian / Ubuntu 中可以通过下面方式一并安装：

sudo apt install -y python3-sphinxcontrib.plantuml plantuml

如果是使用系统的Python环境，安装到此就可以结束了。

在独立的Python环境中，可以通过下面方式进一步安装 Sphinx 的PlantUML扩展。

pip install sphinxcontrib-plantuml

这个扩展需要安装，其发布地址为： https://pypi.org/project/sphinxcontrib-plantuml/

6.3.2. 使用#

在 conf.py 中配置以启用Sphinx的PlantUML扩展：

extensions = [
    'sphinxcontrib.plantuml',
]

可能需要在 conf.py 中声明 plantuml 命令：

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

作为替代方案，可以进行如下处理：

cat <<EOT > /usr/local/bin/plantuml
!/bin/sh -e
java -jar /path/to/plantuml.jar "$@"
EOT
chmod +x /usr/local/bin/plantuml

Then, write PlantUML text under the .. uml:: directive:

or specify path to an external PlantUML file:

You can specify height, width, scale and align:

You can also specify a caption:

Caption with bold and italic

For details, please see PlantUML documentation.

6.3.3. Configuration#

  • plantuml : Path to plantuml executable. (default: plantuml )

  • plantuml_output_formatType of output image for HTML renderer. (default: png )

    • png : generate only .png inside </img>

    • svg : generate .svg inside <object/> with .png inside </img> as a fallback . When svg is inside <object/> it will always render full size, possibly bigger than the container. When svg is inside <img/> it will respect container size and scale if necessary.

    • svg_img : generate only .svg inside <img/> (browser support)

    • svg_obj : generate only .svg inside <object/> (browser support)

    • none : do not generate any images (ignore uml directive)

  • plantuml_latex_output_formatType of output image for LaTeX renderer. (default: png ) Because embedded png looks pretty bad, it is recommended to choose pdf for pdflatex or eps for platex.

    • eps : generate .eps (not supported by pdflatex)

    • pdf : generate .eps and convert it to .pdf (requires epstopdf)

    • png : generate .png

    • tikz : generate .latex in the TikZ format

    • none : do not generate any images (ignore uml directive)

  • plantuml_epstopdf : Path to epstopdf executable. (default: epstopdf)

  • plantuml_syntax_error_image : Should plantuml generate images with render errors. (default: False )

  • plantuml_cache_path : Directory where image cache is stored. (default: _plantuml)

  • plantuml_batch_size : (EXPERIMENTAL) Run plantuml command per the specified number of images. (default: 1 )

If enabled, plantuml documents will be first written to the cache directory, and rendered in batches. This eliminates bootstrapping overhead of Java runtime and allows plantuml to leverage multiple CPU cores.

To enable batch rendering, set the size to 100-1000.

6.3.4. 示例（修改自“sphinx-plantuml”项目）#

警告

以下内容修改自 zqmillet/sphinx-plantuml 。 这个项目同样实现了在 Sphinx 中进行 PlantUML 绘图的功能，区别在于：

sphinx-plantuml 利用 https://plantuml.com 网站对 PlantUML 代码进行渲染

原项目说明：

在 Sphinx 中, 你可以使用 sphinx-contrib/plantuml 在文档中插入 PlantUML 图片. 但是构建环境需要配置 Java 以及 PlantUML 相关 jar 包, 配置起来比较麻烦. 此外, 本地编译也比较慢, 拖慢整个构建过程.

因此我开发了 sphinx-plantuml 库, sphinx-plantuml 的优点有:

  • 纯 Python 库, 无需配置任何环境或者依赖, 开箱即用.

  • 快速的构建速度, 因为构建过程无需编译 PlantUML.

  • 兼容内置 figure 命令大部分参数, 容易上手.

  • 支持 .uml 文件的引用, 便于项目管理.

PlantUML 是可以用纯文本语言绘制图表的开源软件. PlantUML 支持许多统一建模语言, 也支持其他软件开发相关的格式, 比如 C4 模型/电脑网络图/ER 模型/甘特图/心智图和工作分解结构图等, 也可以用在 JSON 及 YAML 文档的可视化.

sphinx-plantuml 原理#

sphinx-plantuml 工作原理如 图 6.3.1 所示.

图 6.3.1 sphinx-plantuml 工作原理#

sphinx-plantuml 安装#

使用 python3 -m pip install sphinx-plantuml 安装 sphinx-plantuml.

然后在你的 conf.py 文件中添加插件的引用, 如下代码所示.

extensions = [
    ...
    'sphinxcontrib.plantuml',
    ...
]

sphinx-plantuml 使用#

sphinx-plantuml 提供了 plantuml 命令. 你可以直接在 plantuml 中写 UML 语言, 比如 代码 6.3.1 所示的 reST 代码.

代码 6.3.1 可以直接 plantuml 环境中写 UML 代码#
.. plantuml::
    :align: center

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

图 6.3.2 代码 6.3.1 渲染效果#

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

代码 6.3.2 指定图片渲染格式#
.. plantuml::
    :align: center
    :format: png

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

图 6.3.3 png 渲染效果#

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

代码 6.3.3 指定图片标题#
.. plantuml::
    :align: center
    :format: png
    :caption: 苟利国家生死以, 岂因祸福避趋之

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

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

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

代码 6.3.4 指定图片宽度#
.. plantuml::
    :align: center
    :format: png
    :width: 50%

    @startuml
    Alice -> Bob: test
    @enduml

其渲染结果如下图所示.

图 6.3.5 50% 宽度的图片#

注解

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

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

代码 6.3.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 模型示例
    :width: 50%
    :align: center

代码 6.3.5 中的代码的渲染效果如下所示.

.. uml:: ./umls/aws_demo.uml
    :width: 50%
    :caption: AWS 示例

.. uml:: ./umls/c4_demo.uml
    :caption: C4 模型示例
    :width: 50%

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

- :download:`insert_html.uml <./umls/insert_html.uml>`;
- :download:`aws_demo.uml <./umls/aws_demo.uml>`;
- :download:`c4_demo.uml <./umls/c4_demo.uml>`.
目录