由于我们在项目工作中计划要试用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目录下。