tjsdoc-plugin-jspm 是一个用于生成项目文档的 TypeDoc 插件,它为使用 jspm 的项目生成文档提供了便利。
在这篇文章中,我们将会深入了解如何使用 tjsdoc-plugin-jspm 解决 TypeScript 项目文档生成的问题,我们还会涵盖指导意义和实际示例。
什么是 tjsdoc-plugin-jspm
tjsdoc-plugin-jspm 是 TypeDoc 的一个插件,它为使用 jspm 的项目提供文档生成便利。这个插件可以帮助开发者自动生成项目的文档,并且提供了许多例外处理选项,支持定制化程度高。
下面是一些 tjsdoc-plugin-jspm 的特性:
- 支持 JSPM 的模块路径解析。
- 支持以模块路径为相对路径构建 URL。
- 可以用正则表达式来过滤文档输出。
- 可以用配置文件中的 JSON 字段实现文档自定义。
- 可以设置别名来为模块提供更有意义的名称。
开始使用 tjsdoc-plugin-jspm
安装
使用 tjsdoc-plugin-jspm 前,你需要先为你的项目初始化 TypeDoc 和 jspm。如果你的项目尚未使用过这些工具,请先在您的项目的根目录下运行命令:
npm init
安装 TypeDoc:
npm install typedoc --save-dev
然后安装 tjsdoc-plugin-jspm:
npm install tjsdoc-plugin-jspm --save-dev
准备工作
保持 TypeDoc 的默认配置不变,将以下 JSON 代码拷贝到你的项目中一个名为 typedoc.json
的文件中:
{ "exclude": ["node_modules", "gulpfile.ts", "gulpfile.js", "typings/**/*.d.ts"], "out": "./docs/", "module": "commonjs", "target": "es5", "readme": "./README.md" }
这要确保文档生成的位置是项目根目录下的 docs/
文件夹。
配置插件
接下来,修改 typedoc.json
文件,加入 tjsdoc-plugin-jspm 的配置项:
-- -------------------- ---- ------- - ---------- ---------------- -------------- -------------- --------------------- ------ ---------- --------- ----------- --------- ------ --------- -------------- --------- ----------------------- --------------------- - ------- ------ ------ ----------------- ------------------ ----- -------- - ---- ------- -- ------------------- - ------- ----- -- ----------------------- ----- --------------------- ----- ------ ----------- - -展开代码
这里列出了一些常用配置项:
root
:指定项目的源代码根目录,可以是绝对路径或相对路径。ext
:指定要生成文档的文件的扩展名。将 tjsdoc-plugin-jspm 与jsdoc
一起使用时,需要使用.js|.jsx|.d.ts
。skipNodeModules
:过滤掉node_modules
目录中的模块文件。alias
:为模块路径提供别名。renameExtensions
:将所有*.tsx
文件的扩展名重命名为.md
。如果需要忽略某些文件,请在include
和exclude
中使用正则表达式。includeCodeInContent
:将代码插入到内容中。unresolvedWarnings
:在生成日志中发出有关未处理导入的警告。url
:构建文档 URL 的格式。
运行生成器
接下来,在项目的根目录下运行 TypeDoc 命令,生成项目文档。
npx typedoc
在这个过程中,如果一切顺利,你应该会看到类似这样的输出:
Using TypeScript 3.5.3 from /home/me/myproject/node_modules/typescript/lib Rendering [========================================] 100% Documentation generated at /home/me/myproject/docs/index.html Time: 0ms
然后你将能在你的项目根目录下的 docs/
文件夹中,找到 HTML 格式的文档输出。
结论
我们在这篇文章中已经了解了如何使用 tjsdoc-plugin-jspm 在 TypeScript 项目中生成文档。我们涵盖了指导意义、用法、设置选项、示例代码和通用错误,为你下一个项目的 TypeDoc 文档准备了一个非常完善的工具包。不管你是为项目文档初部署,还是作为 TypeDoc 文档的老手,tjsdoc-plugin-jspm 都是一款值得推荐的插件。
来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/6005542e81e8991b448d1826