npm 包 gulp-mdox 使用教程

前言

前端开发，特别是在自动化构建方面，有很多强大的工具，不太了解这些工具可能会增加我们的工作量以及失去一些工业化的效益。

本文介绍一款用于生成代码文档的 gulp 插件 gulp-mdox，希望通过这篇文章，可以使大家对于如何使用 gulp-mdox 有一个更全面更深入的了解。

知识储备

在学习本篇文章之前，需要拥有以下基础知识：

• gulp
• markdown

安装

使用 npm 进行安装，全局安装

npm i -g gulp-mdox

使用

安装完毕之后，在 gulpfile.js 文件中引用

const mdox = require("gulp-mdox");

然后在 gulp 任务中调用：

gulp.task("mdox", function() {
  gulp.src("src/**/*.js")
    .pipe(mdox())
    .pipe(gulp.dest("./docs/"));
});

以上代码将会扫描 src 目录及其所有子目录中的所有 JavaScript 文件，并从中解析出注释从而生成相应的文档，最终到处在 docs 目录中。

配置项

• theme：

  生成文档的主题。支持的选项有："markdown"，"markdown-toc"，"javadoc"。

  .pipe(mdox({
          theme: "markdown"
      }))

• name：

  设置文档标题

  .pipe(mdox({
          name: "Awesome Project API",
      }))

• template：

  自定义模板。默认情况下，gulp-mdox 会使用内置的模板去渲染您的文档。

  .pipe(mdox({
          template: "path/to/custom/template.ejs"
      }))

示例

下面是一个简单的示例：

-- -------------------- ---- -------
----- ---- - ----------------
----- ---- - ---------------------

----------------- ---------- -
  -----------------------
    ------------
          ------ -----------
          ----- -------- ------- ----
      ---
    ----------------------------
---

结论

gulp-mdox 是一个非常棒的代码文档生成工具，同时也非常简单易懂。大家可以将其集成到自己的项目中，以便于自己代码的管理和日后维护。

参考文献

• gulp-mdox - npm
• Generate Documents using markdown and jsdoc

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eef14b1efcef77a054b7550