sphinx文檔使用graphviz來畫圖例子

sphinx文檔使用graphviz來畫圖這個看起來有點怪其實不怪了我們這裡來為各位介紹一篇關於sphinx文檔使用graphviz來畫圖的例子。

Sphinx是用來寫文檔的利器，雖然比Markdown來的麻煩一些，但是功能強大，用起來也還很不錯。考慮到不同文檔之間內的跳轉，還有把文檔從拆分成多個小文檔，而且reStructuredText語言入門成本不高，所以用了sphinx-docs來做文檔的編寫。

用Word來編寫文檔？呃。。。請賜我一刀。使用Word來進行編排文檔，在多人協作的情況下，簡直慘不忍睹，文檔的格式亂七八糟。

reStructuredText再通過LeTax來編譯生成pdf也是很方便的。

為什麼要用graphviz來畫圖？

畫圖的軟件並不是太多，一般的人會選擇使用visio來進行畫圖，visio來畫圖確實可以，也無可厚非，所見即所得，容易上手。但是用於一個版本控制的文檔，visio的版本控制就不是太好了。用文本來說就方便很多了。

有個ditaa使用ascii字符來畫圖的，http://ditaa.sourceforge.net/。很多工業界的IETF文檔用它來畫圖

+--------+   +-------+    +-------+
|  cRED  | --+ ditaa +--> |       |
|  Text  |   +-------+    |diagram|
|Document|   |!magic!|    |  cGRE |
|     {d}|   | cYEL  |    |       |
+---+----+   +-------+    +-------+
    :                         ^
    |       Lots of work      |
    +-------------------------+

ditaa

但是和中文結合在一起排版就不是太好了。中文一個字符占兩個英文字符的位置，導致原圖不和諧。還有另外一個原因，感覺編譯ditaa的速度有些慢。

下載安裝Graphviz

Windows下載Graphviz，解壓到一個路徑下，然後把其bin目錄加入到環境變量中。在cmd中dot -V來驗證是否可以使用dot編譯了。

Linux請使用系統自帶的包管理程序來安裝atp-get install graphviz，和Windows同樣的驗證方法。

Sphinx 配置文件修改

Sphinx項目也需要做一些變更，因為開啟了Graphviz插件。修改conf.py，

# 通過配置開啟graphviz插件
extensions = ['sphinx.ext.graphviz']

# 設置 graphviz_dot 路徑
graphviz_dot = 'dot'
# 設置 graphviz_dot_args 的參數，這裡默認了默認字體
graphviz_dot_args = ['-Gfontname=Georgia',
                     '-Nfontname=Georgia',
                     '-Efontname=Georgia']
# 輸出格式，默認png，這裡我用svg矢量圖
graphviz_output_format = 'svg'

這裡graphviz_dot的值是dot，為了不把絕對路徑寫到配置中，防止其他人的路徑不一樣，所以這裡要求dot這個程序在環境變量中，能夠直接使用。

graphviz_dot_args這個參數注意正確使用'-Gfontname=Microsoft YaHei'，以下是錯誤的'-Gfontname="Microsoft YaHei"'。 通過-G, -N, -E 來設置全局的 graph、node、edge 屬性。

開始使用Graphviz

好了，接下來就可以在sphinx文檔中插入你的圖片了。

例如：

.. graphviz::

    digraph abc{
        a;
        b;
        c;
        d;

        a -> b;
        b -> d;
        c -> d;
}

demo圖

 

或者通過

.. graphviz:: external.dot
這個使用一個dot文件內容。

測試一下你的graphviz能否支持好中文

.. 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"];
   }

如果你的graphviz能夠對上面的片段能夠輸出全部的中文，那麼你的graphviz就對中文支持很好了。如圖：

 

中文識別不太好

如果使用Windows的可能node節點裡面的文字會看不見，而Linux下的graphviz可以工作的很好。

在中文label的前面增加一個空白字符,要使用以下的：

.. 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"];
}

修正後，可以更好的支持中文了。