JavaScript 的 API 文件產生器:YUI Doc

此篇文章最近更新時間為2008-12-30 03:02:28 目前共有2篇留言

關於作者 - JosephJ

任職於 Faria。喜好戶外運動、2008 年 5 月完成「跑步環島」。對於新技術跟程式碼有著強烈的偏執狂。

YUIDocs 產出範例頁面圖示

簡介

只要是有在寫程式且參與團隊開發的工程師,絕對會非常重視 API 文件的產出,但若要獨立於程式外再寫一份,再維護性或正確度上都會是很大的問題。YUI Doc 是以 Python 寫的 API 文件產生器,類似著名的 Doxgen 利用程式碼的註解為產生來源,支援許多種 Coding Style。版面使用 YUI 的 JavaScript 與 CSS,所以對熟悉 YUI 的人來說很容易做客製化。

而它強在哪邊呢?用查詢過 YUI API Documentation 一定很喜歡他的搜尋自動完成(AutoComplete)介面、很好找資料。 另外它是專屬於 JavaScript 的,可滿足 JavaScript 開發者的特殊需求,這也是比較少見的。

而 YUI Docs 自從 2005 年起就一直由 Adam Moore 開發、維護用在 YUI 官網上,現在開放給大眾使用並持續改進。 開發者可以利用 YUI Doc 來建立 API 文件產生的自動流程,對於程式開發團隊會很有幫助。

所需套件

安裝所需軟體如下:
  1. YUI Doc
  2. python-setuptools: distribution/packaging tools
  3. python-pygments:Python 的語法高亮
  4. python-simplejson:Python 的JSON 工具函式庫
  5. python-cheetah:Python 的樣板引擎

安裝流程

我是用 Debian Linux 做為開發環境,所以直接用 apt-get 做為安裝套件的範例

sudo apt-get install python
sudo apt-get install python-setuptools
sudo apt-get install python-pygments
sudo apt-get install python-simplejson
sudo apt-get install python-cheetah
curl http://yuilibrary.com/downloads/yuidoc/yuidoc_1.0.0b1.zip > yuidoc_1.0.0b1.zip
unzip yuidoc_1.0.0b1.zip
cd yuidoc
mkdir src
mkdir docs
mkdir parser
curl http://yui.yahooapis.com/2.5.2/build/dom/dom-debug.js > src/dom-debug.js // 抓個原始檔做範例
cd bin
vim example.sh //修改路徑
chmod +x * // 將所有檔案設定為可執行
./example.sh
執行修改後的 example.sh 即可:
YUI Doc 編譯過程
產出的頁面就在 ./docs/ 下:
YUI Doc 產生的頁面
有 AutoCompelte 的 API 文件搜尋很棒吧!接下來我就想好好花點時間修改一下 template,製作屬於自己的樣式。

相關連結

改進 tag 的格式 shell script 撰寫 至少需要有下列其中一個 tag module, class, property, method 或 event. /** * The ProfilerViewer module provides a graphical display for viewing * the output of the YUI Profiler . * @module profilerviewer * @requires yahoo, dom, event, element, profiler, yuiloader */ Primary 與 Secondary 的 Tag 可自訂 YUI Doc 的 template


Comments

  1. 秦歌 2008-12-30 21:45:18
    是很不错,我也写了篇如何开始使用YUI Doc工具http://www.mybloglog.com/buzz/members/dancewithnet/
  2. Squall 2008-12-30 21:07:30
    感覺還不錯,不知道是否也有支援PHP Code?
暱稱: 必填。
Email: 非必填。若填寫為不公開欄位,僅供站長參考聯繫。
內容: 必填。限 255 個字元以內。
驗證碼:
送出

Facebook Comment