大笨鳥的私房菜

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
    

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

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. 存檔

1. 打開 C:\yuidoc\bin\yuidoc_highlight.py
    
2. 找到『out.writelines(highlighted)』(約在第 57 行)
    
3. 將『out.writelines(highlighted)』改成
   『out.writelines(highlighted.encode('UTF-8'))』
    
4. 存檔。

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 向下延續的問題。
    

• YUI DOC 官網
• 隨網起舞
• Python 教學文件 - 3.1.3 Unicode 字串