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/