【www.bbyears.com--中文酷站】
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"];
}
修正后，可以更好的支持中文了。
