如何快速生成JavaScript文件

EER發表於2018-02-27
JavaScript

JSDoc Template

記得有大神說過，儘量不要註釋，除了JsDoc。JsDoc 可以幫助我們通過 JsDoc 的註釋風格快速生成 Api 文件。比如 lodash 文件。

JsDoc 可以讓開發者養成良好的註釋風格，並且可以讓你註釋和編寫文件同步進行。

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

相關文章