mkdocs-diagrams

这是一个用于MkDocs文档站点生成器的插件，它通过Diagrams项目（查看示例）方便地嵌入系统架构图表。

安装

mkdocs-diagrams可在PyPI上找到。您可以通过pip install mkdocs-diagrams或等效的pipenv或poetry命令进行安装。

您还需要在您的系统上安装graphviz的dot工具。它在大多数包管理器中作为graphviz提供。

安装后，通过在您的mkdocs.yml中的plugins列表中包含diagrams来配置MkDocs以使用此插件。例如

plugins:
  - diagrams
  - search

(如果您还没有配置plugins密钥，您几乎肯定还会想要包含search。这是一个默认插件，否则将不会启用。)

用法

警告: 此插件将在构建期间执行.diagram.py文件，因为Diagrams本身就是这样操作的。在使用此插件处理不可信输入时要小心，因为这实际上允许任意代码执行。

安装后，可以在文档目录中包含图表文件来使用图表插件。

例如，创建一个名为example.diagrams.py的文件，内容如下

from diagrams import Cluster, Diagram
from diagrams.aws.compute import ECS, EKS, Lambda
from diagrams.aws.database import Redshift
from diagrams.aws.integration import SQS
from diagrams.aws.storage import S3


with Diagram("Event Processing", show=False):
    source = EKS("k8s source")

    with Cluster("Event Flows"):
        with Cluster("Event Workers"):
            workers = [ECS("worker1"),
                       ECS("worker2"),
                       ECS("worker3")]

        queue = SQS("event queue")

        with Cluster("Processing"):
            handlers = [Lambda("proc1"),
                        Lambda("proc2"),
                        Lambda("proc3")]

    store = S3("events store")
    dw = Redshift("analytics")

    source >> workers >> queue >> handlers
    handlers >> store
    handlers >> dw

当MkDocs运行（无论是使用build还是serve）时，这将生成一个名为event_processing.png的文件。使用常规图像语法将其包含在Markdown文件中：![事件处理架构](event_processing.png)

配置

此插件支持一些配置选项，设置方法如下

plugins:
  - diagrams:
      file_extension: ".diagrams.py"
      max_workers: 5

file_extension

设置图表文件的文件扩展名。当运行 mkdocs build 或 mkdocs serve 时，所有以此扩展名结尾的文件都将被执行。

默认值: .diagrams.py

max_workers

在多核系统上，使用工作池并行渲染图表文件。设置此选项可以限制工作进程的数量。

默认值: 动态选择 (os.cpu_count() + 2)