Sphinx文档嵌入Graphviz图形可视化

Graphviz 是一款开源图形可视化软件。图形可视化是一种将结构信息表示为抽象图形和网络图表的方式。它在网络、生物信息学、软件工程、数据库和网页设计、机器学习以及其他技术领域的可视化界面中有着重要的应用。

备注

目前我还很少使用Graphviz，不过在以往工作中曾经使用过作为绘制工作流。本文仅做简单整理记录，以便后续能够参考完成一些文档撰写的图示参考。

准备工作

对于需要渲染文档的主机，需要先安装 Graphviz官网提供的GraphViz工具集。对于 macOS 平台可以使用 Homebrew 安装:

macOS 平台使用 Homebrew 安装 Graphviz

brew install graphviz

Sphinx配置

修订 Sphinx 文档的 conf.py 配置:

激活 Graphviz 扩展

extensions = [
        'sphinx.ext.graphviz',
        'sphinxnotes.strike',
        'sphinxcontrib.youtube',
        'sphinxcontrib.video',
        'myst_parser'
]

# -- GraphViz configuration ----------------------------------
graphviz_output_format = 'svg'

撰写文档嵌入Graphviz的案例代码:

嵌入 Graphviz 的代码案例

.. graphviz::
    :name: sphinx.ext.graphviz
    :caption: Sphinx and GraphViz Data Flow
    :alt: How Sphinx and GraphViz Render the Final Document
    :align: center

     digraph "sphinx-ext-graphviz" {
         size="6,4";
         rankdir="LR";
         graph [fontname="Verdana", fontsize="12"];
         node [fontname="Verdana", fontsize="12"];
         edge [fontname="Sans", fontsize="9"];

         sphinx [label="Sphinx", shape="component",
                   href="https://www.sphinx-doc.org/",
                   target="_blank"];
         dot [label="GraphViz", shape="component",
              href="https://www.graphviz.org/",
              target="_blank"];
         docs [label="Docs (.rst)", shape="folder",
               fillcolor=green, style=filled];
         svg_file [label="SVG Image", shape="note", fontcolor=white,
                 fillcolor="#3333ff", style=filled];
         html_files [label="HTML Files", shape="folder",
              fillcolor=yellow, style=filled];

         docs -> sphinx [label=" parse "];
         sphinx -> dot [label=" call ", style=dashed, arrowhead=none];
         dot -> svg_file [label=" draw "];
         sphinx -> html_files [label=" render "];
         svg_file -> html_files [style=dashed];
     }

显示效果
- nodes具有一个 href 属性， SVG 渲染后包含 可点击的超链接

Sphinx and GraphViz Data Flow

Sphinx文档嵌入Graphviz图形可视化

准备工作

Sphinx配置

参考