萬盛學電腦網

瀏覽器 Windows 10 WPS Office 防毒軟體 資料庫 Excel 教學 檔案管理 Word 教學 網頁製作 裝機必備軟體 Linux 教學

您现在的位置： 萬盛學電腦網 >> 程式設計 >  >> 資料庫 >> MySQL 教學

Sphinx + Graphviz 文檔繪圖實戰：從安裝配置到中文渲染避坑全記錄

技術文檔維護中，版本可控的圖表是剛需。Visio 雖好用但二進制難比對；Graphviz 用 DOT 語言描述圖形，純文本友好 Git diff，配合 Sphinx 實現文檔與圖表同源管理。本文記錄 Windows/Linux 安裝、Sphinx 配置、中文渲染踩坑全過程。

為什麼選 Graphviz？

  • 文本化：DOT 源碼可版本控制、可 Code Review
  • 自動佈局：無需手動拖拽，算法自動優化節點位置
  • 輸出多樣：支援 PNG、SVG、PDF 等矢量/位圖格式
  • 生態成熟：Sphinx 官方擴展 sphinx.ext.graphviz 零成本集成

環境準備

Windows

  1. 下載 Graphviz 安裝包
  2. 解壓並將 bin 目錄加入系統 PATH
  3. 驗證：dot -V 輸出版本號即成功

Linux (Debian/Ubuntu/CentOS)

apt-get install graphviz   # 或 yum/dnf
dot -V  # 驗證

Sphinx 配置啟用

編輯 conf.py：

# 啟用擴展
extensions = ['sphinx.ext.graphviz']

# Graphviz 執行路徑（需在 PATH 中）
graphviz_dot = 'dot'

# 全域字體設置（關鍵：解決中文顯示）
graphviz_dot_args = [
    '-Gfontname=Microsoft YaHei',
    '-Nfontname=Microsoft YaHei',
    '-Efontname=Microsoft YaHei'
]

# 輸出 SVG 矢量圖，縮放不失真
graphviz_output_format = 'svg'

注意：-G/-N/-E 分別設置圖/節點/邊屬性，字體名不可加引號，錯誤寫法：'-Gfontname="Microsoft YaHei"'。

文檔中嵌入圖表

內聯 DOT 代碼

.. graphviz::

   digraph abc {
       a; b; c; d;
       a -> b;
       b -> d;
       c -> d;
   }

引用外部 .dot 文件

.. graphviz:: external.dot

中文渲染：從亂碼到完美的踩坑路

問題現場

直接寫中文標籤，Windows 下節點文字消失，Linux 顯示方框/亂碼。

解決方案：字體 + 前置空格

.. graphviz::

   digraph idp_modules {
       fontname = "Microsoft YaHei";
       rankdir = TB;
       fontsize = 12;
       node [fontname = "Microsoft YaHei", fontsize = 12, shape = "record"];
       edge [fontname = "Microsoft YaHei", fontsize = 12];

       subgraph cluster_sl {
           label = " IDP支持層";        # 關鍵：前置一個全角/半角空格
           bgcolor = "mintcream";
           node [shape = "Mrecord", color = "skyblue", style = "filled"];
           network_mgr [label = " 網絡管理器"];
           log_mgr [label = " 日誌管理器"];
           module_mgr [label = " 模塊管理器"];
           conf_mgr [label = " 配置管理器"];
           db_mgr [label = " 數據庫管理器"];
       }

       subgraph cluster_md {
           label = " 可插拔模塊集";
           bgcolor = "lightcyan";
           node [color = "chartreuse2", style = "filled"];
           mod_dev [label = " 開發支持模塊"];
           mod_dm [label = " 數據建模模塊"];
           mod_dp [label = " 部署發布模塊"];
       }

       mod_dp -> mod_dev [label = "依賴..."];
       mod_dp -> mod_dm [label = "依賴..."];
       mod_dp -> module_mgr [label = "安裝...", color = "yellowgreen", arrowhead = "none"];
       mod_dev -> mod_dm [label = "依賴..."];
       mod_dev -> module_mgr [label = "安裝...", color = "yellowgreen", arrowhead = "none"];
       mod_dm -> module_mgr [label = "安裝...", color = "yellowgreen", arrowhead = "none"];
   }

核心技巧總結

  1. 字體必須系統安裝：Windows 需安裝微軟雅黑，Linux 需 apt-get install fonts-wqy-zenhei 等
  2. 標籤前置空格：label = " 中文" 繞過 Graphviz 中文斷詞 bug
  3. 統一字體配置：graphviz_dot_args 全域設置避免重複
  4. 優先 SVG 輸出：矢量無失真，Web 直接嵌入

進階替代方案對比

工具優點缺點適用場景
Graphviz自動佈局、文本化、生態成熟複雜佈局微調困難架構圖、流程圖、ER 圖
ditaaASCII 畫圖、極簡中文對齊極難、編譯慢簡單時序圖、IETF 文檔
MermaidMarkdown 原生、語法簡潔Sphinx 需額外擴展、大圖性能弱輕量級文檔、README
PlantUMLUML 全品類、功能強需 Java 運行時、學習曲線陡專業建模、序列圖、類圖

Graphviz + Sphinx 是「文檔即代碼」理念的最佳實踐之一。掌握中文渲染技巧，讓技術文檔圖文並茂、版本可控、團隊協作無障礙。

MySQL 教學排行

推薦文章

萬盛學電腦網| 日本語版 | 設為首頁 | 加入收藏

copyright © 萬盛學電腦網 all rights reserved