YUI Doc 是一套 YAHOO YUI 團隊開發出來專門用來產生 Javascript API 文件的程式,經由 YUI Doc 所產生出來的 API 長得就和 YUI 官網上的 API 文件格式是一樣的。
 
YUI Doc 雖然是一個不錯用的工具,但是安裝起來有點麻煩,因此本篇文章就是要介紹如何在 Windows 環境下將 YUI Doc 一次安裝到好。

步驟一: 
 首先電腦中要先安裝 Python 和 setuptools。
Python 使用的是 2.4.3 到 2.5 之間版本,雖然 Python 的版本已經到 3.0.1 了,但是由於 setuptools 最多只支援到 Python 2.5 版,因此 Python 最好不要超過 2.5 版。

(以下範例使用 Python 2.4.3)
  1. 下載 Python
    http://www.python.org/ftp/python/2.4.3/python-2.4.3.msi
     
  2. 安裝 Python。
    預設的安裝路徑為『C:\Python24』
     
  3. 下載 setuptools
    http://pypi.python.org/pypi/setuptools
     
    因為在範例中安裝的是 Python 2.4.3 版,所以請下載其中的
    setuptools-0.6c9.win32-py2.4.exe
     
  4. 安裝 setuptools。
     
  5. 將 Python 的安裝路徑加入 Windows 的環境變數 Path。
    1. 在『我的電腦』上按滑鼠按鍵,並在跳出來的選單上選擇『內容』。
       
    2. 點擊『進階』,並按下『環境變數』按鈕。
       
    3. 在『系統變數』的變數列表中找出『Path』,並在其上點擊滑鼠左鍵兩次。
       
    4. 將 Python 的安裝路徑『C:\Python24』加到『變數值』欄位中。如果變數值欄位中已有值,請用分號隔開。如:
      C:\Java6.0\bin;C:\Python24。
       
    5. 一路按下『確定』鈕離開。
步驟二: 
 

在成功安裝完 Python 和 setuptools 之後,就可以使用 easy install 的功能了。
因此接下來要使用 easy install 功能來安裝 pygments、Cheetah 與 simplejson。

  1. 進入 easy install 執行檔目錄。
    CD C:\Python24\Scripts
    (註:C:\Python24 為Python 的安裝路徑)
     
  2. 安裝 pygments。請 key 入下列指令。
    easy_install pygments
     
  3. 安裝 Cheetah。請 key 入下列指令。
    easy_install Cheetah
     
  4. 安裝 simplejson。請 key 入下列指令。
    easy_install simplejson
     
請注意:pygments、Cheetah 與 simplejson 不需要上網 download,因為當你使用 easy_install 指令時,它會自動上網去抓取檔案下來安裝。
步驟三: 
 下載並安裝 YUI Doc。
  1. 下載 YUI Doc
    http://yuilibrary.com/downloads/yuidoc/yuidoc_1.0.0b1.zip
     
  2. 解壓下載回來的 Zip 檔。
    在此範例中,將解壓到 C:\yuidoc
     
  3. 安裝 _namemapper.pyd。
    將 C:\yuidoc\ext\_namemapper.pyd 複製到
    C:\Python24\Lib\site-packages\cheetah-2.0.1-py2.4.egg\Cheetah
步驟四: 
 修改 YUI DOC 的 example.bat
  1. 打開 C:\yuidoc\bin\example.bat
     
  2. 修改以下的參數
    REM 此為 YUI DOC 的目錄,在此範例中為 C:\yuidoc
    SET yuidoc_home="c:\yuidoc"
     
    REM 要生成 API 的 js 路徑。
    REM 如果有多個路徑,用空白隔開,例如:
    REM     SET parser_in="c:\myJS\js c:\Event.dev\src"
    SET parser_in="C:\testyuidoc\jsdata"
     
    REM YUI DOC 會把解析的 js 提取出來放置在此路徑上
    SET parser_out="C:\testyuidoc\parser"
     
    REM YUI DOC 產生出來的 API 文件會放置在此路徑上
    SET generator_out="C:\testyuidoc\jsdatadoc"
     
  3. 存檔
一般來說,只要執行到步驟四之後,就能執行 example.bat 來解析 js 檔並產生出 API 文件,但是若你的 js 檔內的註解(/** ... */)包含了中文,則會丟出『TypeError: writelines() argument must be a sequence of strings』的錯誤。這個問題的原因是 YUI DOC 不支援中文!那該如何解決呢?請參照下面的步驟五。
 
步驟五: 
 修改 YUI DOC 程式以支援中文註解
  1. 打開 C:\yuidoc\bin\yuidoc_highlight.py
     
  2. 找到『out.writelines(highlighted)』(約在第 57 行)
     
  3. 將『out.writelines(highlighted)』改成
    out.writelines(highlighted.encode('UTF-8'))
     
  4. 存檔。
再執行一次 example.bat,你會發現已經能夠成功的產生出中文註解的 API 了。
 
後記: 
 如果 js 註解中缺少了『@module』與『@class』是無法成功產生 API 的。
少了『@module』雖然只會產生 API 的 index 文件,但卻無法產出該 js 檔的 API 文件。
而少了『@class』則會在執行 example.bat 時,直接丟出錯誤。
 
後續補充:
 
  1. 產生的 API 文件中,Modules 和 Files 無法吻合。
    有二個 js 檔,放置的路徑分別為:
    C:\js\BaseJS\event\EventUtils.js (module 設為 event) 與 C:\js\BaseJS\form\FormUtils.js (module 設為 form),
    example.bat parser_in="C:\js\BaseJS"
     
    此時產生出來的 API 文件中,選擇 module event 時,其對應到的 Files 除了 EventUtils.js 之外,竟然還有 FormUtils.js。而選擇 module form 時,竟然沒有 Files 欄位,表示 module form 沒有對應到任何 js。

    此問題應該是 parser_in 指到這兩個 js 共有的父欄位,造成了 YUI DOC 將這兩個獨立的 js 當成是互有關聯(同一個實體 module?)來看待,因此解決之法是將這兩個 js 路徑在 parser_in 中分開寫,如下:
    parser_in=C:\js\BaseJS\event C:\js\BaseJS\form

    由以上得知,最好不同的 module 不要放在同一個目錄下,以免 YUI DOC 發生誤判。
     
  2. 同一個 js 檔有兩個 module
    YUI DOC 可以解析出同一個 js 檔有兩個 module 的情況,但是在產生出來的 API 文件中,第二個 module 就不會對到任何一個 js 檔 (即沒有 Files 欄位),因此建議若一個 js 檔有兩個 module 的清況,最好還是分開成兩個 js 檔比較好。
     
  3. @namespace 具有向下延展性,甚至會跨到同一個 module 下的不同 js 檔。
    當我們在某一個類別註解 @class 上多加上一行 @namespace 時,在此類別之後的所有類別都會自動被加上 namespace。
    例如:
    有一個類別上的註解為
    /**
       * @namespace YAHOO.util
       * @class FormUtils
       */
     
    則此 class 最後呈現在 API 文件上的 class 名稱為 YAHOO.util.FOrmUtils。
    接著,在此類別之後我們又寫一個類別註解
    /**
       * @class EventUtils
       */

    這個類別我們並沒有給他任何的 namespace,但在 API 文件中呈現出來的卻是 YAHOO.util.EventUtils。由此我們可以看到在某個類別被設定了 namespace 之後,這個 namespace 將會一直存在於描述於此類別之後的任何一個類別,就算之後的類別是寫在別的 js 檔,但只要是同一個 module,namespace 仍會一直延續下去。

    要解決這個問題,我們只能在加了 namespace 類別的下一個類別中加上一個空的 namespace。如下:

    /**
       * 這是加了 namespace 的類別
       * @namespace YAHOO.util
       * @class FormUtils
       */
    /**
       * 在加了 namespace 類別的下一個類別中
       * 加上一個空的 namespace
       * @namespace
       * @class EventUtils
       */

     如此就能解決 namespace 向下延續的問題。
     
參考文件:

創作者介紹
創作者 大笨鳥 的頭像
大笨鳥

大笨鳥的私房菜

大笨鳥 發表在 痞客邦 留言(0) 人氣()