Posted on 2009-04-11 15:08
sailor 閱讀(386)
評論(0) 編輯 收藏 所屬分類:
javascript
YUI Doc 是一個很好的
JavaScript API 文檔生成工具
http://developer.yahoo.com/yui/yuidoc
生成的前提是注釋寫法符合Jsdoc標準和YUI給出的標準
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的官方文檔和YUIblog上的《YUI Doc: A New Tool for Generating JavaScript APIDocumentation》（由于YUI blog咱們無法訪問，比較好的解決方案就是在Google Reader中訂閱它的Feed，直接輸入
http://yuiblog.com即可。）
YUI Doc是基于Python開發，且依賴幾個擴展庫，加之其
Getting Started寫的也比較含糊，所以如何使用這個工具反而成為第一道門檻，尤其對于那些對Python不熟悉的同學來說。所以，下面的重點是介紹如何在Windows上使用YUI Doc：
- 下載Python2.5.2安裝之。
雖然Python3.0和Python2.6都已經出來很久了，但之所以依舊選擇Python2.5.2，是因為后面要用到的安裝Python擴展庫的工具setuptools在Windows下的最新版本對應的是Python2.5。我不知道它是否支持2.5以上，有興趣的可以試試。
- 下載setuptools-0.6c9.win32-py2.5.exe并安裝之，setuptools會自動安裝到Python所在安裝目錄的Scripts目錄下。
setuptools為Python提供了簡單的包管理和發行功能。后面的擴展庫的安裝就是利用它的easy_install，非常方便。有興趣的可以看看《可愛的 Python: 使用 setuptools 孵化 Python egg》。
- 為了使用方便需要配置一下“環境變量”，即在“我的電腦 》右鍵 》屬性 》高級 》環境變量 》系統變量 》 選中Path 》 編輯”，在彈出框中加入：;D:\Program Files\python;D:\Program Files\python\Scripts然后應用即可。前面的兩個路徑分別是我的Python和setuptools的安裝路徑，你需要修改成你自己的。
- 開始 》運行 》(Win + R)輸入“cmd”，輸入：python -c "import pkg_resources"沒有任何輸出，即表示setuptools安裝成功。接著依次輸入運行：
easy_install Pygments
easy_install simplejson
easy_install Cheetah
setuptools會自動尋找并下載Pygments、SimpleJSON和Cheetah這三個擴展庫，并安裝它。
- 下載YUI Doc，并解壓在某個目錄下。復制其bin目錄下的example.bat文件，重命名為test.bat，然后用記事本或其他編輯器打開并配置它:SET yuidoc_home="D:\yui\yuidoc"
REM YUI Doc的路徑
parser_in="D:\yui\src"
REM 要生成文檔的JS文件路徑，比如為了測試就我臨時建一個，里面就放著YUI 的 dom.js
parser_out="D:\yui\src\parser"
REM YUI Doc會把解析的JS文件提取出來所要存放的位置
generator_out="D:\yui\src\generator"
REM 生成文檔存放的位置
保存并運行test.bat后，就會發現D:\yui\src中多了parser和generator兩個目錄，而generator中正是你要的文檔。
學會使用工具僅僅是開始了一小步，仔細看看
YUI Doc的官方文檔吧，利用其來促使我們寫出更高效優雅的前端代碼并惠及更多的人才是一大步