jsdoc to markdown

原文：https://www.npmjs.com/package/jsdoc-to-markdown

markdown API文件生成器

本文件是一個工作正在進行中

jsdoc在文件的原始碼輸入，markdown 格式的API文件輸出。

概要

寫檔案的程式碼：

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

執行命令：

$ jsdoc2md example/src/protection.js

得到 markdown 的文件！ （用github-flavored-markdown 預設格式）

<a name="protection"></a>
## protection(cloak, dagger) ⇒ <code>survival</code>
a quite wonderful function

| Param  | Type                | Description  |
| ------ | ------------------- | ------------ |
| cloak  | <code>object</code> | privacy gown |
| dagger | <code>object</code> | security     |

這個命令可以實現相同的結果：

$ jsdoc-parse example/function.js | dmd

特徵

• 將API機制的文件插入一個README，或任意檔案。
• 自定義一個規則水平。如果輸出不適合你，改變它。
• 打包您的修改，釋出到NPM並與他人分享（如dmd-bitbucket）
• accepts.js或.html輸入檔案（解析HTML是實驗性的 - 更多）
• 擴充套件了jsdoc用一些新的標籤（更多）
• 使用任意標記，例如@fulfil，@reject，@hatredlevel等。

示例輸出

一些示例輸出建立使用jsdoc2md。

生成的自述檔案

這些專案中插入jsdoc2md輸出到readme模板。

專案	筆記
handbrake-js	模組露出兩個方法和一個內部類。 API文件插入readme模板通過此命令：$ jsdoc2md –template jsdoc2md/README.hbs lib/*.js
array-tools	很簡單的模組輸出的靜態方法的集合。演示使用@typicalname的（設定為a）和@Category標籤組識別符號在成員列表中。
ansi-escape-sequences	演示使用@enum{型別}（以表格形式呈現）。
file-set	簡單的模組匯出類。

標籤

你可以看到對每一jsdoc標記看起來當呈現在這裡時的一個例子。

例項演示各種選項
為了得到一個想法的影響的各種選項有：

• 格式化選項
  
  • example-lang
  • module-index-format
  • global-index-format
  • member-index-format
  • param-list-format
  • property-list-format
  • no-gfm
  • separators
  • name format
• 解析選項
  
  • html
  • sort-by

指令碼示例

如果你使用命令列工具不能實現你所需要的，你可以寫一個自定義指令碼。

• 生成 markdown 檔案每一個類

模板例項

預設jsdoc2md輸出可能並不總是適合你。您可以使用自己的模板,使用該模板選項。你可以看到用來生成這個readme的模板。

選擇器

• Cherry-pick 其中文件出現輸出使用選擇助手。
  
  • {{#module}}
  • {{#class}}

安裝和使用

首先，您的原始碼文件使用正確的jsdoc語法，然後通過jsdoc-to-markdown 使用以下方法（在Mac OSX，Linux和windows8.1和Windows XP的所有測試）：

命令列工具

要全域性安裝jsdoc2md命令列工具，執行：

$ npm install -g jsdoc-to-markdown

一些典型使用案例：

$ # dump everything you have into a single file 
$ jsdoc2md "src/**/*.js" > api.md

$ # split into separate files 
$ jsdoc2md src/main-module.js > main-module.md
$ jsdoc2md src/important-class.js > important-class.md

$ # embed documentation into a template you made 
$ jsdoc2md "src/**/*.js" --template readme.hbs > README.md

注意在通配

一般規則：如果你的檔案表示式中包含* * 遞迴尚未失敗，用引號括起表示式（例如”lib/* * / *.js”）。

如果用引號包裹，bash（或你的shell）不會試圖檔名擴充套件在表示式上。如果不使用引號，你將需要bash的版本4+與globstar啟用遞迴工作。

新增“生成文件”任務到你的專案工作流程

作為npm的執行任務
這是最輕量級的方式新增任務 - 不需要額外任務執行的軟體。第一：

$ npm install jsdoc-to-markdown --save-dev

隨後，package.json的“scripts”一節中，新增一個文件的任務。 例如：

{
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

現在，專案文件，像這樣產生的：

$ npm run docs

作為一個grunt任務
看 grunt-jsdoc-to-markdown.

作為一個gulp任務
看 gulp-jsdoc-to-markdown.

貢獻
問題報告和補丁的鼓勵。而該專案將受益於額外的維護..

組成
從本質上講，jsdoc2d連線jsdoc-parse的輸出到DMD的輸入。 DMD使用DDATA輔助庫（也由DHTML共享）和資料流以產生輸出。

API參考

例子

var jsdoc2md = require("jsdoc-to-markdown");

jsdoc2md([options]) ⇒ TransformStream ⏏
變換jsdoc到markdown的文件。

kind:匯出的函式
params

• [options] DmdOptions | ParseOptions - the options

例子

兩種方法來使用jsdoc2md。無論是傳遞檔案路徑（**全域性匹配支援）JavaScript原始檔：

> jsdoc2md({ src: "lib/*.js" }).pipe(process.stdout);

或管道中的原始碼來自其他資源：

fs.createReadStream("lib/main.js").pipe(jsdoc2md()).pipe(process.stdout);

dmd~DmdOptions

所有DMD選項及其預設值

kind:DMD的內部類

• ~DmdOptions
  
  • .template : string
  • .heading-depth : number
  • .example-lang : string
  • .plugin : array
  • .helper : array
  • .partial : array
  • .name-format : string
  • .no-gfm : boolean
  • .separators : boolean
  • .module-index-format : string
  • .global-index-format : string
  • .param-list-format : string
  • .property-list-format : string
  • .member-index-format : string
  • .group-by : array

dmdOptions.template : string

該模板所提供的文件會被渲染成。使用預設或提供自己的模板完全控制的輸出。

kind:DmdOptions的例項屬性
default:”{{>main}}”

例子

var fs = require("fs");
var dmd = require("../");

var template = "The description from my class: {{#class name='MyClass'}}{{description}}{{/class}}";

fs.createReadStream(__dirname + "/my-class.json")
    .pipe(dmd({ template: template }))
    .pipe(process.stdout);

輸出：

The description from my class: MyClass is full of wonder

使用命令列工具的equivation操作：

$ dmd --template template.hbs --src my-class.json

dmdOptions.heading-depth : number

最初的標題深度。例如，具有值2的頂層markdown標題看起來像“##的標題”。

kind:DmdOptions的例項屬性
default:2

dmdOptions.example-lang : string

指定使用@example塊（語法高亮顯示的目的）的預設語言。在GFM模式下，每個@example被包裹在一個 fenced-code塊。用法示例：–example-lang js。使用特殊值none因為沒有特定的語言。在使用這個選項，你可以覆蓋語言提供任何@example通過指定@lang子標籤，如@example @lang hbs。指定@example @lang off將禁用程式碼塊的例子。

kind:DmdOptions的例項屬性
default:”js”

dmdOptions.plugin : array

使用含有幫助 和/或 部分覆蓋安裝的軟體包

kind:DmdOptions的例項屬性

dmdOptions.helper : array

處理幫助程式檔案來覆蓋或繼承預設設定
kind:DmdOptions的例項屬性

dmdOptions.partial : array

處理部分檔案覆蓋或繼承預設設定
kind:DmdOptions的例項屬性

dmdOptions.name-format : string

在程式碼樣式格式識別符號名稱，（即使用反引號格式的或）
kind:DmdOptions的例項屬性

dmdOptions.no-gfm : boolean

預設情況下，DMD產生github-flavoured的markdown。並非所有的markdown解析器正確地呈現GFM。如果您生成的文件看起來不正確的網站上比其他Github上（如npmjs.org）嘗試啟用這個選項來禁用Github-specific 的語法。

kind:DmdOptions的例項屬性

dmdOptions.separators : boolean

把

---

放在識別符號之間。提高了笨重文件的可讀性。

kind:DmdOptions的例項屬性
default:false

dmdOptions.module-index-format : string

none, grouped, table, dl

Kind: DmdOptions的例項屬性
Default: “dl”

dmdOptions.global-index-format : string

none, grouped, table, dl
Kind: DmdOptions的例項屬性
Default: “dl”

dmdOptions.param-list-format : string

兩個選項渲染引數列表：’list’或’table’（預設值）。表格式適用於大多數情況下，但切換到列表中，如果事情開始變得擁擠/壓扁。

Kind: DmdOptions的例項屬性
Default: “table”

dmdOptions.property-list-format : string

list, table

Kind: DmdOptions的例項屬性
Default: “table”

dmdOptions.member-index-format : string

grouped, list

Kind: DmdOptions的例項屬性
Default: “grouped”

dmdOptions.group-by : array

域的列表，以組成員索引

Kind: DmdOptions的例項屬性
Default: [“scope”,”category”]

jsdocParse~ParseOptions
所有jsdoc-parse選項，其中包括預設

kind:jsdocParse 的內部類

• 解析選項
  
  • .src : string | Array.
  • .private : boolean
  • .stats : boolean
  • .html : boolean
  • .sort-by : array

parseOptions.src : string | Array.

原始檔進行解析。如果沒有設定這個選項jsdoc-parse會等待輸入到流式傳輸。

kind:ParseOptions的例項屬性
例子

var parse = require("jsdoc-parse");
var fs = require("fs");

// either supply one or more file names 
parse({ src: "example.js" }).pipe(process.stdout);

// or pipe in source code 
fs.createReadStream("example.js").parse().pipe(process.stdout);

parseOptions.private : boolean

包括識別符號文件標記為@private在輸出

Kind: ParseOptions的例項屬性
Default: false

parseOptions.stats : boolean
列印有關doclet解析的數統計
Kind: ParseOptions的例項屬性

parseOptions.html : boolean

啟用的.html檔案的實驗分析。

Kind: ParseOptions的例項屬性
Default: false

parseOptions.sort-by : array
排序通過其中一個欄位，例如 –sort-by kind 類別。

Kind: ParseOptions的例項屬性
Default: [“scope”,”category”,”kind”,”order”]