NPM 包 tjsdoc-plugin-jspm 使用教程

阅读时长 5 分钟读完

tjsdoc-plugin-jspm 是一个用于生成项目文档的 TypeDoc 插件,它为使用 jspm 的项目生成文档提供了便利。

在这篇文章中,我们将会深入了解如何使用 tjsdoc-plugin-jspm 解决 TypeScript 项目文档生成的问题,我们还会涵盖指导意义和实际示例。

什么是 tjsdoc-plugin-jspm

tjsdoc-plugin-jspmTypeDoc 的一个插件,它为使用 jspm 的项目提供文档生成便利。这个插件可以帮助开发者自动生成项目的文档,并且提供了许多例外处理选项,支持定制化程度高。

下面是一些 tjsdoc-plugin-jspm 的特性:

  • 支持 JSPM 的模块路径解析。
  • 支持以模块路径为相对路径构建 URL。
  • 可以用正则表达式来过滤文档输出。
  • 可以用配置文件中的 JSON 字段实现文档自定义。
  • 可以设置别名来为模块提供更有意义的名称。

开始使用 tjsdoc-plugin-jspm

安装

使用 tjsdoc-plugin-jspm 前,你需要先为你的项目初始化 TypeDoc 和 jspm。如果你的项目尚未使用过这些工具,请先在您的项目的根目录下运行命令:

安装 TypeDoc:

然后安装 tjsdoc-plugin-jspm

准备工作

保持 TypeDoc 的默认配置不变,将以下 JSON 代码拷贝到你的项目中一个名为 typedoc.json 的文件中:

这要确保文档生成的位置是项目根目录下的 docs/ 文件夹。

配置插件

接下来,修改 typedoc.json 文件,加入 tjsdoc-plugin-jspm 的配置项:

-- -------------------- ---- -------
-
  ---------- ---------------- -------------- -------------- ---------------------
  ------ ----------
  --------- -----------
  --------- ------
  --------- --------------
  --------- -----------------------
  --------------------- -
    ------- ------
    ------ -----------------
    ------------------ -----
    -------- -
      ---- -------
    --
    ------------------- -
      ------- -----
    --
    ----------------------- -----
    --------------------- -----
    ------ -----------
  -
-
展开代码

这里列出了一些常用配置项:

  • root:指定项目的源代码根目录,可以是绝对路径或相对路径。
  • ext:指定要生成文档的文件的扩展名。将 tjsdoc-plugin-jspmjsdoc 一起使用时,需要使用 .js|.jsx|.d.ts
  • skipNodeModules:过滤掉 node_modules 目录中的模块文件。
  • alias:为模块路径提供别名。
  • renameExtensions:将所有 *.tsx 文件的扩展名重命名为 .md 。如果需要忽略某些文件,请在 includeexclude 中使用正则表达式。
  • includeCodeInContent:将代码插入到内容中。
  • unresolvedWarnings:在生成日志中发出有关未处理导入的警告。
  • url:构建文档 URL 的格式。

运行生成器

接下来,在项目的根目录下运行 TypeDoc 命令,生成项目文档。

在这个过程中,如果一切顺利,你应该会看到类似这样的输出:

然后你将能在你的项目根目录下的 docs/ 文件夹中,找到 HTML 格式的文档输出。

结论

我们在这篇文章中已经了解了如何使用 tjsdoc-plugin-jspm 在 TypeScript 项目中生成文档。我们涵盖了指导意义、用法、设置选项、示例代码和通用错误,为你下一个项目的 TypeDoc 文档准备了一个非常完善的工具包。不管你是为项目文档初部署,还是作为 TypeDoc 文档的老手,tjsdoc-plugin-jspm 都是一款值得推荐的插件。

来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/6005542e81e8991b448d1826

纠错
反馈

纠错反馈