如何开始使用YUI Doc工具？（补充版）

 

　　由于我们在项目工作中计划要试用YUI Doc，但不知如何入手，遂上Google搜索，找到的基本都是《如何开始使用YUI Doc工具？》一文。根据此文入手，发现其中已经部分不适用，因此我根据我的环境的实际情况和结合官方的YUI Doc文档，修正了部分内容并记录下来。以下开始还是引用原文，并以红色文字作为注解或修正：

 

　　YUI Team实践出了一个高效易协作的前端代码开发流程：代码首先由Ant来组织管理和版本化、接着由JsLint来验证，然后由YUI Doc文档化、最后由YUI Compressor进行压缩发布。上个月初，YUI Team公布了这个新的JavaScript API文档生成工具YUI Doc，它本来专门为YUI提供API级别的文档的，现在它开源为人民服务了。

 

　　YUI Doc和JavaDoc、JSDoc和JsDoc Toolkit相似。YUI Doc是由注解驱动（comment-driven ）的系统，它通过解析代码中描述结构的注解来生成文档。由于它纯粹的依赖于注解，所以并不像一些模拟系统一样需要有惯用语和代码模式。更详细的介绍可以看YUI Doc的官方文档和YUI blog上的《YUI Doc: A New Tool for Generating JavaScript API Documentation》（由于YUI blog咱们无法访问，比较好的解决方案就是在Google Reader中订阅它的Feed，直接输入 http://yuiblog.com即可。）

 

　　YUI Doc是基于Python开发，且依赖几个扩展库，加之其Getting Started写的也比较含糊，所以如何使用这个工具反而成为第一道门槛，尤其对于那些对Python不熟悉的同学来说。所以，下面的重点是介绍如何在Windows上使用YUI Doc：

　　1、下载Python2.5.2安装之。

 

 

　　我测试环境是Window XP SP3英文版，YUI Doc版本为1.0.0b1，用的Python版本2.4.3，安装Python到D盘的Python24下。

 

 

　　虽然Python3.0和Python2.6都已经出来很久了，但之所以依旧选择Python2.5.2，是因为后面要用到的安装Python扩展库的工具setuptools在Windows下的最新版本对应的是Python2.5。我不知道它是否支持2.5以上，有兴趣的可以试试。

 

　　SetupTool最新版本已经支持Python2.7了，但是保险起见，这里我们还是使用2.4.3，2.7的问题最后简单说明。

 

　　2、下载setuptools-0.6c9.win32-py2.5.exe并安装之，setuptools会自动安装到Python所在安装目录的Scripts目录下。

 

　　根据Python版本，我这里下载的是setuptools-0.6c11.win32-py2.4.exe，运行后会自动找到相应的Python目录，不知道是Python的版本原因还是什么的，安装的路径是在：D:/Python24/Lib/site-packages下，Python2.7和相应的SetupTools也是一样。

 

　　setuptools为Python提供了简单的包管理和发行功能。后面的扩展库的安装就是利用它的easy_install，非常方便。有兴趣的可以看看《可爱的 Python: 使用 setuptools 孵化 Python egg》。

 

　　3、为了使用方便需要配置一下“环境变量”，即在“我的电脑 -> 右键 ->属性 ->高级 ->环境变量 -> 系统变量 -> 选中Path -> 编辑”，在弹出框中加入： 

　　;D:/Program Files/python;D:/Program Files/python/Scripts

 

　　我根据本机安装情况，这里增加的是：

　　;D:/Python24;D:/Python24/Lib/site-packages/setuptools;D:/Python24/Lib/site-packages

 

然后应用即可。前面的两个路径分别是我的Python和setuptools的安装路径，你需要修改成你自己的。

　　4、开始 -> 运行 -> (Win + R)输入“cmd”，输入： 

　　python -c "import pkg_resources"

 

　　没有任何输出，即表示setuptools安装成功。接着依次输入运行：

　　easy_install Pygments

　　easy_install simplejson

　　easy_install Cheetah

 

　　这里我按照以上步骤来做没有成功，无非就是提示路径命令找不到之类的错误。只好在命令行中输入：CD D:/Python24/Lib/site-packages，先转到easy_install安装目录，然后依次运行如下才可以：

　　Python easy_install.py Pygments

　　Python easy_install.py simplejson

　　Python easy_install.py Cheetah

 

　　setuptools会自动寻找并下载Pygments、SimpleJSON和Cheetah这三个扩展库，并安装它。

 

　　这里顺便提一下，我安装的版本分别为Pygments：1.3.1，cheetah：2.4.2.1，然后安装Cheetah时候会报一个依赖相关错误如下，不知道是不是只有我安装时才有这个问题，反正出现了就记录下来：

…

Processing dependencies for Cheetah
Searching for Markdown>=2.0.1
Reading http://pypi.python.org/simple/Markdown/
Reading http://www.freewisdom.org/projects/python-markdown/
Reading http://www.freewisdom.org/projects/python-markdown
Reading https://sourceforge.net/project/showfiles.php?group_id=153041
Best match: Markdown 2.0.3
Downloading http://sourceforge.net/projects/python-markdown/files/markdown/2.0.3/Markdown-2.0.3.win32.exe/download
Processing download
error: Couldn't find a setup script in c:/docume~1/xxxx/locals~1/temp/1/easy_install-xayneh/download

 

　　解决的方法也很简单，照着错误给出来的Markdown 2.0.3下载路径下载后，手动安装就可以解决问题，加粗的文字部分就是。

 

　　5、下载最新版本YUI Doc，并解压在某个目录下。复制其bin目录下的example.bat文件，重命名为test.bat，然后用记事本或其他编辑器打开并配置它: 

　　SET yuidoc_home="D:/yui/yuidoc"

　　REM YUI Doc的路径

　　SET parser_in="D:/yui/src"

　　REM 要生成文档的JS文件路径，比如为了测试就我临时建一个，里面就放着YUI 的 dom.js

　　SET parser_out="D:/yui/src/parser"

　　REM YUI Doc会把解析的JS文件提取出来所要存放的位置

　　SET generator_out="D:/yui/src/generator"

　　REM 生成文档存放的位置

 

　　保存并运行test.bat后，就会发现D:/yui/src中多了parser和generator两个目录，而generator中正是你要的文档。

 

　　支持中文注释的解决方案

 

　　1、下载最新版本YUI Doc，解决方案在yuidoc-27中验证通过

　　2、把所有.js文件都转成不带BOM的UTF-8编码

　　3、修改文件/bin/yuidoc_highlight.py： 

　　from pygments.formatters import HtmlFormatter

　　#新增下行

　　import codecs

　　...

　　#f=open(os.path.join(path, file))

　　#fileStr=StringIO(f.read()).getvalue()

　　#f.close()

　　fileStr = codecs.open( os.path.join(path, file), "r", "utf-8" ).read()

　　log.info("highlighting " + file)

 

　　#highlighted = highlightString(fileStr)

　　highlighted = highlightString(unicode(fileStr))

　　4、在Python的/Lib/site-packages/下增加一个名为sitecustomize.py的文件，其内容为： 

　　import sys

　　sys.setdefaultencoding('utf-8')

 

　　最后说一下，在Windows Xp Sp2 + Python 2.4.3和64位Windows 2003 Std Server + Python 2.7环境下都测试安装成功，当然64位环境下的Python 2.7是32位版本的，因为SetupTools不支持64位的Python。

　　使用Python 2.7的时候有个问题百思不得其解，就是生成的html文件字节数为0，也无法生成index.html，提示错误为：

TypeError: unbound method respond() must be called with yuidoc_template_main_tmpl instance as first argument (got nothing instead)，其他的Parser Data也能正常生成，如果有纯64位下和Python 2.7下成功的请告知我一下方法，谢谢！