东东东 陈煜东的博客

标签存档: sphinx-docs

Graphviz安装失败的一个尝试

Graphviz来对sphinx进行画图,不过发现一直无法编译出来。

PS:Graphviz的官网在大陆访问非常的慢。

首先参考http://graphviz.org/Download_linux_rhel.php,增加一个repo源,

然后执行yum install 'graphviz*'安装graphviz的软件。

在安装的过程中出现了

Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Hashtbl) = 718cd6ce8bc18371ce22483e362f78b4
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Hashtbl) = 024edc3512403b725052aec8e41ed971
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Array) = 4d5efba91ec70acd7b184fd4b277708c
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Array) = 8a6bb22925744456eb66180ea42e3344
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(List) = bd7c662c09e850306a62c12fed5ef5ce
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(List) = d757117653d9319fefb7ddc78a998f41
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(runtime) = 4.00.1
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(runtime) = 4.01.1
ocaml(runtime) = 4.01.0
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Gc) = 23b8d067f883f7a218c4945a42625a31
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Gc) = 292a1cd61d8e068943589882415bdf7d
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Obj) = ad977b422bbde52cd6cd3b9d04d71db1
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Obj) = b0adfa4175f86e4394859886c1a374bb
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Int32) = 265928798c0b8a63fa48cf9ac202f0ce
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Int32) = ad06f04cfca6d404d1de76c3dc67324a
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Callback) = 6fd6d47b2f6a171a493621bc5edbfb32
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Callback) = 198fb4bcde892143b0866b03cfae8085
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(List) = bd7c662c09e850306a62c12fed5ef5ce
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(List) = d757117653d9319fefb7ddc78a998f41
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Callback) = 6fd6d47b2f6a171a493621bc5edbfb32
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Callback) = 198fb4bcde892143b0866b03cfae8085
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Pervasives) = 4836c254f0eacad92fbf67abc525fdda
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Pervasives) = 36b5bc8227dc9914c6d9fd9bdcfadb45
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Hashtbl) = 718cd6ce8bc18371ce22483e362f78b4
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Hashtbl) = 024edc3512403b725052aec8e41ed971
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Pervasives) = 4836c254f0eacad92fbf67abc525fdda
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Pervasives) = 36b5bc8227dc9914c6d9fd9bdcfadb45
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Array) = 4d5efba91ec70acd7b184fd4b277708c
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Array) = 8a6bb22925744456eb66180ea42e3344
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(runtime) = 4.00.1
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(runtime) = 4.01.1
ocaml(runtime) = 4.01.0
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Int32) = 265928798c0b8a63fa48cf9ac202f0ce
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Int32) = ad06f04cfca6d404d1de76c3dc67324a
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Gc) = 23b8d067f883f7a218c4945a42625a31
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Gc) = 292a1cd61d8e068943589882415bdf7d
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Int64) = 0d5ecd8dffcffac43aec2ebe427d3bde
Available: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Int64) = 3945db6e8df0d5a79bcbc949ee550d52
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Obj) = ad977b422bbde52cd6cd3b9d04d71db1
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Obj) = b0adfa4175f86e4394859886c1a374bb
Error: Package: graphviz-lang-ocaml-2.38.0-1.el7.x86_64 (graphviz-stable)
Requires: ocaml(Int64) = 0d5ecd8dffcffac43aec2ebe427d3bde
Installing: ocaml-runtime-4.01.0-22.6.el7.x86_64 (base)
ocaml(Int64) = 3945db6e8df0d5a79bcbc949ee550d52
You could try using --skip-broken to work around the problem
You could try running: rpm -Va --nofiles --nodigest

看这个论坛说,修改之后,再次安装,果然可以装上。

Just edit the snapshot section so that “enabled=1”, and correspondingly disable the stable section.

[graphviz-snapshot]
name=Graphviz - RHEL $releasever - $basearch
baseurl=http://www.graphviz.org/pub/graphviz/development/redhat/el$releasever/$basearch/os/
enabled=1
gpgcheck=0
skip_if_unavailable=1

[graphviz-snapshot-source]
name=Graphviz - RHEL $releasever - Source
baseurl=http://www.graphviz.org/pub/graphviz/development/SRPMS/
enabled=1
gpgcheck=0
skip_if_unavailable=1

最后安装的dot程序

dot - graphviz version 2.39.20160710.1729 (20160710.1729)
libdir = "/usr/lib64/graphviz"
Activated plugin library: libgvplugin_dot_layout.so.6
Using layout: dot:dot_layout
Activated plugin library: libgvplugin_core.so.6
Using render: dot:core
Using device: dot:dot:core
The plugin configuration file:
        /usr/lib64/graphviz/config6
                was successfully loaded.
    render      :  cairo dot dot_json fig gd json json0 map mp pic pov ps svg tk vml vrml xdot xdot_json
    layout      :  circo dot fdp neato nop nop1 nop2 osage patchwork sfdp twopi
    textlayout  :  textlayout
    device      :  bmp canon cmap cmapx cmapx_np dot dot_json eps fig gd gd2 gif gtk gv ico imap imap_np ismap jpe jpeg jpg json json0 mp pdf pic plain plain-ext png pov ps ps2 svg svgz tif tiff tk vml vmlz vrml wbmp x11 xdot xdot1.2 xdot1.4 xdot_json xlib
    loadimage   :  (lib) bmp eps gd gd2 gif ico jpe jpeg jpg pdf png ps svg xbm

PS:如果有些程序没有安装好,那么没办法生成pdf的格式。

如下面的错误信息,硬是没有pdf的格式。原来是插件没有安装全。

Graphviz produced errors. Verify it has support for filetype=pdf, or use filetype=dot.
Original error: Format: "pdf" not recognized. Use one of: canon cmap cmapx cmapx_np dot eps fig gd gd2 gif gv imap imap_np ismap jpe jpeg jpg plain plain-ext png ps ps2 svg svgz tk vml vmlz vrml wbmp xdot

不过还残留一个没有解决的问题

[stderr]
Warning: flat edge between adjacent nodes one of which has a record shape - replace records with HTML-like labels
  Edge A -> B
Error: lost A B edge

我把两个node放在同一个level,然后做了箭头,报错了,得再研究研究。

声明:未经允许禁止转载 东东东 陈煜东的博客 文章,谢谢。如经授权,转载请注明: 转载自东东东 陈煜东的博客

本文链接地址: Graphviz安装失败的一个尝试 – https://www.chenyudong.com/archives/graphviz-install-fail.html

分类: Python, 软件

sphinx doc正式支持中文搜索啦

之前Sphinx doc一直不支持web的中文搜索,一个牛逼的项目怎么能不支持中文搜索呢。看到现在这个项目的一个负责人是日本人,目前支持CJK的的搜索就是日本了,我觉得不应该呀,我大中华人杰辈出。果然在github上的pull request看到了台湾的enhao兄提交了繁体中文的搜索,看了代码的实现,里面是支持中文搜索的,于是在他的基础上修改了一些完善了简体中文的支持。

我一直觉得sphinx-doc这个项目很不错,可以写文档,写书,多多关注关注一下issue的列表。

上线发布

现在sphinx-doc的master或者v1.4版本后就支持中文(简体+繁体)搜索了。

sphinx-doc的中文搜索是依靠jieba这个开源的类库来实现的,这个类库就支持简体和繁体的切分,所以就很容易实现了。

使用

第一,你的系统需要安装jieba类库, pip install jieba

第二,接下来修改sphinx的conf.py文件,为项目设置为中文的搜索配置。

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
html_search_language = 'zh'

第三,可选配置

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
# html_search_options = {'dict': '/usr/lib/jieba.txt'}   # 根据需要设置jieba的词典路径

第四,接下来重新编译生成文档。make html

sphinx的基本搜索原理

在编译的时候:

  1. 先对文本进行切词,把中文切分,
  2. 然后制作一个大的map对象,把关键字做为key,url做为value,保存到js文件。
  3. 搜索的时候寻找对应的关键字key,拿到url作为列表展示。

后续计划

上线比较匆忙,还有一些中文搜索的计划

  • 支持python3的搜索
  • 添加测试的用例

声明:未经允许禁止转载 东东东 陈煜东的博客 文章,谢谢。如经授权,转载请注明: 转载自东东东 陈煜东的博客

本文链接地址: sphinx doc正式支持中文搜索啦 – https://www.chenyudong.com/archives/sphinx-doc-support-chinese-search.html

分类: Python

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 来设置全局的 graphnodeedge 属性。

开始使用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"];
   }

修正后,可以更好的支持中文了。

修正后,中文识别的更好

参考

声明:未经允许禁止转载 东东东 陈煜东的博客 文章,谢谢。如经授权,转载请注明: 转载自东东东 陈煜东的博客

本文链接地址: sphinx文档使用graphviz来画图 – https://www.chenyudong.com/archives/sphinx-docs-draw-graphic-with-graphviz.html

分类: 实用技巧

Copyright © 2017 东东东 陈煜东的博客 粤ICP备13059639号-1

SITEMAP回到顶部 ↑