Pyke 简介 (7) ：修改 Pyke

1、使用 Mercurial 管理开发版本

Mercurial 是个分布式版本控制系统，可用它把 Pyke 项目复制到本地硬盘上，进行修改。你若要发布到 sourceforge，可以 email 给我审查。

① Mercurial 的关键字扩展

Pyke 项目管理最初是用 SVN，现在为了与之兼容，使用着 Mercurial 的关键字扩展。

如果使用 Mercurial "后期复制"（post-clone）功能，或者在复制后手工补充文件hgrc_keywords，那么，在项目首次复制后，关键字的扩展不会完整。可先后用 -U 和 hg 选项，使之完整。

关键字的扩展，只用于生成html文档的工具。

② 该用哪个版本？

通常应该把 sourceforge 上的以下四个版本之一，复制本地硬盘。

release_1

这个版本是为了纠错、净化代码、净化文本而保留的原始版本。用于Python 2.x和3.x的Pyke均由此变化而来。

pyke

这个版本用于发布新的重要功能。它的起始版是 release_1，后继版是 pre_2to3。可运行在Python 2.x和3.x上。

pre_2to3_r1

这个版本是为了纠错、净化代码、净化文本而保留的原始版本，但只用于Python 3.x。

警示

这个版本运行前需要Python 的版本升级工具 2to3，不能直接运行。

脚本文件 run_2to3 启动 2to3 处理当前版本的源文件。不要在欲托管的版本上直接此操作，改用复制的。若升级不成功，可再试原版的复制本。这可最在限度减少 2to3 引发的故障。

脚本 run_pre_test 运行的结果是：

● 复制当前版本的 Pyke
● 操作复制本：
○ 运行 run_2to3
○ 运行 testpyke -3.1
○ 运行 python setup.py -q sdist --formats zip
○ 把生成的zip文件名"pyke"的后面，插入字符串"3.1"。

运行 Run_pre_test 需要以下条件：在 .hgrc 文件中，设置了关键字选项，或者，.hg/hgrc 文件中有复制功能的设置。

版本 pre_2to3

通常，大部分新功能开始在pyke，修改变化后，一并存入 pri_2to3。如果修改只涉及 Python3.x 的 Pyke，则直接改动 pre_2to3。

例如，如果改动 release_1，则：

$ mkdir pyke_repos

$ cd pyke_repos
$ hg clone -U http://pyke.hg.sourceforge.net:8000/hgroot/pyke/release_1 master
$ hg clone master task_1
$ cd task_1注意

要先把文件 hgrc_keywords 加入 ~/.hgrc 文件。

2、编译 PLY 表格文件

kfbparser_tables.py (from kfbparser.py)

krbparser_tables.py (from krbparser.py)
scanner_tables.py (from scanner.py)

PLY 在源文件目录 pyke/krb_compiler/ply。

要重建这些表格文件，需在源文件的顶层目录操作：

$ python

>>> from pyke.krb_compiler import kfbparser, krbparser, scanner
>>> scanner.init(scanner, 0, True)
>>> krbparser.init(krbparser, True)
>>> kfbparser.init(kfbparser, True)

或者直接运行 doctest-tools 里的程序 "testall"

$ cd pyke/krb_compiler

$ testall

3、编译 .krb 文件

Pyke 把你的知识库文件（.kfb, .kqb 和 .krb）编译成 Python 文件。编译操作要用到知识库 pyke/krb_compiler/compiler.krb。生成

的是文件是 compiler_bc.py。

重新编译文件 compiler_bc.py，在 Pyke 根目录操作：

$ mkdir pyke/krb_compiler/compiled_krb

$ python
>>> from pyke import krb_compiler
>>> krb_compiler.compile_krb('compiler', 'pyke.krb_compiler.compiled_krb',
... 'pyke/krb_compiler/compiled_krb',
... 'pyke/krb_compiler/compiler.krb')
['compiler_bc.py']

$ mv pyke/krb_compiler/compiled_krb/compiler_bc.py pyke/krb_compiler

4、单元测试

单元测试需要软件 doctest-tools，其中脚本 testall 和 testdoc 可在各个目录下运行。

Pyke 根目录下有个脚本 testpyke，运行后会删除目录 compiled_krb，并执行2次 testall。首次执行，会重新编译生成 compiled_krb 中的知识库文件(.krb, .kfb and .kqb )；二次执行，重新使用上述知识库文件，以此确认，全部测试结果是否完好，知识库是否需要编译。

5、重建 HTML 文档

Pyke 文档的.txt 源文件在目录 doc/source，生成的 .html 文件放在 doc/html。编译文档的工具是 rest2web 中的 docutils，用法是：

$ bin/gen_html

程序运行约9秒：

① 暂时把超链接添加到文件 *.txt 中。

② 运行 r2w 生成目录 doc/html 中的文件
○ 不生成 doc/html/stylesheets 和 doc/html/images 中的文件。

③ 从 *.txt 文件中，删除超链接。

④ 创建新文件 sitemap.xml，记下全部文件的最后修改日期。

注意

文件修改日期的信息，用的是Mercurial关键字扩展。

文档可以直接浏览，只有修改 doc/source 的 .txt 文件后，才需运行 bin/gen_html。

测试文档中的例程时，使用 doctest-tools 的命令 testall：

$ cd doc

$ testall

注：doctest-tool 的下载地址是 http://code.google.com/p/doctest-tools/