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"]; }
修正后,可以更好的支持中文了。

修正后,中文识别的更好
参考
- http://chuansong.me/n/939320
- http://icodeit.org/2015/11/using-graphviz-drawing/
- http://sphinx-doc.org/ext/graphviz.html
声明:未经允许禁止转载 东东东 陈煜东的博客 文章,谢谢。如经授权,转载请注明: 转载自东东东 陈煜东的博客
发表评论