JS文檔和Demo自動化生成工具

nikybook 2015-07-31

展開全文

　　曾幾何時，當(dāng)你碼神附體，一路披荊斬棘的完成代碼后，帶著“一碼在手，天下我有”的傲然環(huán)顧之時，卻發(fā)現(xiàn)單元測試、API文檔、Demo實例陸續(xù)向你砸來，頓時有木有一種冰水挑戰(zhàn)后的感覺。而這時你應(yīng)該：喲喲，快使用SmartDoc；

　　SmartDoc，一個基于NodeJS的自動化文檔生成工具，她擁有明眸的雙眼(yuidoc引擎)，華麗的外衣（bootstrap 3風(fēng)格），靈巧的雙手（demo生成，codemirror代碼編輯，jasmine接口兼容）;擁有她，相信你一定會仰天長嘯："小伙伴們再也不用擔(dān)心我的API了?！?/span>

　　最近有不少朋友問我SmartJS的一些API，我使用YUIDoc和bootstrap2的那個主題全部整理了一遍，但發(fā)現(xiàn)只有API沒有具體例子也比較難懂，而且沒有幾個人會看單元測試。遂起念，將文檔、單元測試、demo整合提供完整的生成方案，這就有了SmartDoc。

SmartDoc 0.1.0 新鮮上架

　　具有以下特點：

   * 基于Bootstrp3構(gòu)建，排版和樣式美化
   * 支持html和js的Demo生成,與查看
   * 提供在線的demo編輯頁面（類似于jsfiddler）
   * 同步j(luò)asmine的expect接口，使得單元測試與example的代碼能夠復(fù)用
   * 可以配置化增強 - 項目信息配置；Document頁面導(dǎo)航配置；demo依賴庫配置
   * 提供全局api查詢和導(dǎo)航過濾功能，篩選更加便利
   * 提供grunt插件 - grunt-contrib-smartdoc

`界面講解`

`全局過濾`

通過右側(cè)全局過濾，可以快速檢索所有的API，點擊可以跳轉(zhuǎn)到API頁面并定位到對于的位置；支持全鍵盤操作

`源代碼展示`

點擊代碼位置的鏈接，就可以進入源代碼展示頁面

`Example演示頁面`

點擊Example區(qū)域的Edit Code按鈕開啟代碼編輯頁面，如下：頁面中有HTML和Code兩個編輯區(qū)域和結(jié)果的展示區(qū)域，代碼編輯器使用codemirror，sublime風(fēng)格，支持智能感知，可以通過配置項來引入樣式和腳本庫。提供log和expect公共方法；　　log：在結(jié)果區(qū)輸出日志信息　　expect ：兼容jasmine的expect方法

在example區(qū)域中寫入html代碼時，使用<html>html代碼</html>和<script>js代碼<script>的格式錄入即可；

注1：代碼編輯頁面必須需要服務(wù)器環(huán)境才能正常運行，本地文件方式只能使用view demo頁面查看結(jié)果；

`View Demo頁面`

在Example區(qū)域點擊view demo按鈕或者在code edit頁面點擊view in new window進入；頁面上展示最終結(jié)果

`單獨使用說明`

在目錄中加入docConfig.js文件，詳細配置如下:

module.exports = {
    //掃描的文件路徑
    paths: ['input/'],

    //文檔頁面輸出路徑
    outdir: 'doc/',

    //項目信息配置
    project: {

        //項目名稱
        name: 'SmartDoc',

        //項目描述，可以配置html，會生成到document主頁
        description: '<h2>SmartDoc</h2> <p>Javascript Document builder base on YUIDoc.</p>',

        //版本信息
        version: '1.1.0',

        //地址信息
        url: 'https://github.com/zhh77/smartjs',
        //logo地址
        logo : 'https://github.com/zhh77/logo.png',
        //導(dǎo)航信息
        navs: [{
            name: "Home",
            url: "https://github.com/zhh77/smartjs"
        }, {
            name: "Document",
            url: ""
        }, {
            name: "About",
            url: "https://github.com/zhh77/smartjs"
        }]
    },

    //demo展示頁面配置；需要加載的資源； 資源只能是css和js文件
    demo: {

        //外部資源鏈接
        link : ['http://code./jquery-1.11.0.min.js'],

        //文件復(fù)制路徑; 將目下的資源復(fù)制到doc生成目錄中，并在deom頁面引用
        paths : ['input/ui/uicode.js','input/']

        //是否開啟在code編輯器中的自動完成功能(會將link和paths的引入加入)；默認開啟；
        autoComplete : true
    },

    //自定義主題路徑
    themedir: 'theme/',

    //自定義helpers
    helpers: ["theme/helpers/helpers.js"]
};

運行如下代碼：

npm install -g smartdoc

smartdoc

grunt使用

如果是grunt的話引入grunt-contrib-smartdoc，在grunt配置上述docconfig內(nèi)容；例如：

// 項目配置

    grunt.initConfig({
        pkg: grunt.file.readJSON('package.json'),
        smartdoc: {
            build: {
                options: {
                    paths: ['src/'],
                    outdir: 'doc/',
                    demo: {
                        paths: ['dest/smart.js','dest/smart-dataManager.js'],
                        link: ['http://code./jquery-1.11.0.min.js']
                    },
                    //項目信息配置
                    project: {
                        name: '<%= pkg.name %>',
                        // description: '<%= pkg.description %>',
                        version: '<%= pkg.version %>',
                        url: 'https://github.com/zhh77/smartjs',
                        navs: [{
                            name: "Home",
                            url: "https://github.com/zhh77/smartjs"
                        }, {
                            name: "Document",
                            url: "http://zhh77./smartjs/"
                        }, {
                            name: "Blog",
                            url: "http://www.cnblogs.com/zhh8077"
                        }, {
                            name: "SmartDoc",
                            url: "https://github.com/zhh77/smartDoc"
                        }]
                    }
                }
            }
        },
        …………