Posted on 2009-04-11 15:08
sailor 閱讀(386)
評(píng)論(0) 編輯 收藏 所屬分類:
javascript
YUI Doc 是一個(gè)很好的
JavaScript API 文檔生成工具
http://developer.yahoo.com/yui/yuidoc
生成的前提是注釋寫法符合Jsdoc標(biāo)準(zhǔn)和YUI給出的標(biāo)準(zhǔn)
YUI Team實(shí)踐出了一個(gè)高效易協(xié)作的前端代碼開發(fā)流程：代碼首先由Ant來(lái)組織管理和版本化、接著由
JsLint來(lái)驗(yàn)證，然后由
YUI Doc文檔化、最后由
YUI Compressor進(jìn)行壓縮發(fā)布。上個(gè)月初，YUI Team公布了這個(gè)新的JavaScript API文檔生成工具
YUI Doc，它本來(lái)專門為
YUI提供
API級(jí)別的文檔的，現(xiàn)在它開源為人民服務(wù)了。
YUI Doc和JavaDoc、JSDoc和
JsDoc Toolkit相似。YUI Doc是由注解驅(qū)動(dòng)（comment-driven ）的系統(tǒng)，它通過(guò)解析代碼中描述結(jié)構(gòu)的注解來(lái)生成文檔。由于它純粹的依賴于注解，所以并不像一些模擬系統(tǒng)一樣需要有慣用語(yǔ)和代碼模式。更詳細(xì)的介紹可以看
YUI Doc的官方文檔和YUIblog上的《YUI Doc: A New Tool for Generating JavaScript APIDocumentation》（由于YUI blog咱們無(wú)法訪問(wèn)，比較好的解決方案就是在Google Reader中訂閱它的Feed，直接輸入
http://yuiblog.com即可。）
YUI Doc是基于Python開發(fā)，且依賴幾個(gè)擴(kuò)展庫(kù)，加之其
Getting Started寫的也比較含糊，所以如何使用這個(gè)工具反而成為第一道門檻，尤其對(duì)于那些對(duì)Python不熟悉的同學(xué)來(lái)說(shuō)。所以，下面的重點(diǎn)是介紹如何在Windows上使用YUI Doc：
- 下載Python2.5.2安裝之。
雖然Python3.0和Python2.6都已經(jīng)出來(lái)很久了，但之所以依舊選擇Python2.5.2，是因?yàn)楹竺嬉玫降陌惭bPython擴(kuò)展庫(kù)的工具setuptools在Windows下的最新版本對(duì)應(yīng)的是Python2.5。我不知道它是否支持2.5以上，有興趣的可以試試。
- 下載setuptools-0.6c9.win32-py2.5.exe并安裝之，setuptools會(huì)自動(dòng)安裝到Python所在安裝目錄的Scripts目錄下。
setuptools為Python提供了簡(jiǎn)單的包管理和發(fā)行功能。后面的擴(kuò)展庫(kù)的安裝就是利用它的easy_install，非常方便。有興趣的可以看看《可愛的 Python: 使用 setuptools 孵化 Python egg》。
- 為了使用方便需要配置一下“環(huán)境變量”，即在“我的電腦 》右鍵 》屬性 》高級(jí) 》環(huán)境變量 》系統(tǒng)變量 》 選中Path 》 編輯”，在彈出框中加入：;D:\Program Files\python;D:\Program Files\python\Scripts然后應(yīng)用即可。前面的兩個(gè)路徑分別是我的Python和setuptools的安裝路徑，你需要修改成你自己的。
- 開始 》運(yùn)行 》(Win + R)輸入“cmd”，輸入：python -c "import pkg_resources"沒有任何輸出，即表示setuptools安裝成功。接著依次輸入運(yùn)行：
easy_install Pygments
easy_install simplejson
easy_install Cheetah
setuptools會(huì)自動(dòng)尋找并下載Pygments、SimpleJSON和Cheetah這三個(gè)擴(kuò)展庫(kù)，并安裝它。
- 下載YUI Doc，并解壓在某個(gè)目錄下。復(fù)制其bin目錄下的example.bat文件，重命名為test.bat，然后用記事本或其他編輯器打開并配置它:SET yuidoc_home="D:\yui\yuidoc"
REM YUI Doc的路徑
parser_in="D:\yui\src"
REM 要生成文檔的JS文件路徑，比如為了測(cè)試就我臨時(shí)建一個(gè)，里面就放著YUI 的 dom.js
parser_out="D:\yui\src\parser"
REM YUI Doc會(huì)把解析的JS文件提取出來(lái)所要存放的位置
generator_out="D:\yui\src\generator"
REM 生成文檔存放的位置
保存并運(yùn)行test.bat后，就會(huì)發(fā)現(xiàn)D:\yui\src中多了parser和generator兩個(gè)目錄，而generator中正是你要的文檔。
學(xué)會(huì)使用工具僅僅是開始了一小步，仔細(xì)看看
YUI Doc的官方文檔吧，利用其來(lái)促使我們寫出更高效優(yōu)雅的前端代碼并惠及更多的人才是一大步