Jsdoc-to-markdown

需求

JSDOC生成的文档（html）和现在开发者网站要求的文档格式（markdown）不一致，导致API文档展示不够理想。

调研结果

JSDOC直接生成MD：https://github.com/jsdoc2md/jsdoc-to-markdown，使用demo文件可以直接生成，也可支持ts。

优化方案

1．通过工具jsdoc-to-markdown将js内容生成为md格式文件，与内容文档一致
2．读取不成功的类，跳过，并将错误原因写入log；
3．生成文档索引json文件，便于入库和索引

运用实例

命令 node jsdoc2md.js
参考
https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-create-one-output-file-per-class

Jsdoc2md.js

'use strict'
const jsdoc2md = require('jsdoc-to-markdown')
const fs = require('fs')
const path = require('path')

/* input and output paths */
const inputFile = 'example.js'
const outputDir = __dirname

/* get template data */
const templateData = jsdoc2md.getTemplateDataSync({ files: inputFile })

/* reduce templateData to an array of class names */
const classNames = templateData.reduce((classNames, identifier) => {
  if (identifier.kind === 'class') classNames.push(identifier.name)
  return classNames
}, [])

/* create a documentation file for each class */
for (const className of classNames) {
  const template = `{{#class name="${className}"}}{{>docs}}{{/class}}`
  console.log(`rendering ${className}, template: ${template}`)
  const output = jsdoc2md.renderSync({ data: templateData, template: template })
  fs.writeFileSync(path.resolve(outputDir, `${className}.md`), output)
}