如何快速生成JavaScript文檔

JSDoc Template

記得有大神說過，儘可能不要註釋，除了JsDoc。JsDoc 能夠幫助咱們經過 JsDoc 的註釋風格快速生成 Api 文檔。好比 lodash 文檔。

JsDoc 能夠讓開發者養成良好的註釋風格，而且能夠讓你註釋和編寫文檔同步進行。

• 官方文檔/英文
• 中文參考
• github

myJsDoc 模板預覽

API 文檔風格主要基於 jsDoc Template ，myJsDoc 就是其中衍生的一種風格。全部樣式(包括代碼風格) 都可自定義。

• 總體風格

• markdown 風格 (github)

JsDoc 安裝

npm install -g jsdoc
複製代碼

在根目錄新建 jsdoc.json 用於配置生成規則，以下 ( 具體配置可參考 myJsDoc )

{
    "source": {
        // 須要生成文檔的對應 js 路徑
        "include": ["src/"],
        "includePattern": ".js$"
    },
    "opts": {
        "destination": "docs/", // 文檔生成目錄
        "readme": "docs/index.md", // 文檔首頁展現內容
        "template": "", // 文檔模板
        "package": "package.json",
        "recurse": true,
        "tutorials": "docs/tutorials", // 生成教程內容
        "encoding": "utf8"
    },
    "templates": {
        // 模板配置，此處跟模板設置有關。
    },
    "plugins": ["plugins/markdown"],
    "markdown": {
        "tags": ["example"],
        "idInHeadings": true
    }
}
複製代碼

myJsDoc 模板配置項

{
    "templates": {
      "default": { // 可自定義指定添加到styles的目錄
        "staticFiles": {
            "include": [
                 "./static"
            ]
        }
      },
      "css": [
        "styles/style.css" // 自定義樣式
      ],
      "name": "Doc Template", // 文檔名稱
      "tabNames":{ // 導航名稱
          "tutorials":"wiki",
          "apiName":"api"
      }
  }
}
複製代碼

如何自定義樣式

首先確保項目正常跑起來

git clone https://github.com/leer0911/myJsdoc.git
cd myJsDoc
npm i
npm run serve
複製代碼

這裏，serve 任務主要作了三件事

• 監聽 scss 文件，編譯成 css 對應存入 static 目錄下
• 監聽 jsdoc 相關文件
• 觸發 gulp-jsdoc 生成文檔

模板全部相關資源都在 static 目錄下

• tmpl 目錄 layout.tmpl 修改佈局
• publish.js 修改由 jsdoc 傳入的數據，包括 nav 信息，註釋信息等
• scss 目錄修改樣式

運行 demo 後找到以上主要文件進行實時自定義修改

參考

代碼樣式

jsdoc 經常使用標籤

tui jsdoc