组件文档网站重构(v5)

[nullptr-z]

根据组件API注释自动化产生说明文档

手动管理API说明文档面临的问题：

1. API变化如何追踪？
2. 怎么避免将内部api暴露到外部？
3. 怎么避免忘了导出API的类型声明？
4. 发布 alpha、beta版本的包时，api 如何管理？

工具

microsoft/api-extractor TypeScript 分析工具

• API Report 跟踪项目主入口点的所有导出，并生成一份报告，作为API审查工作流的基础。
• d.ts Rollups 类似于Webpack可以将所有 JavaScript 文件“汇总”到单个包中以进行分发，API Extractor 可以将 TypeScript 声明汇总到单个 .d.ts 文件中。
• API Documentation API Extractor 可以为项目生成一个“文档模型”JSON 文件。这个JSON 文件包含提取的类型签名和文档注释。我们可以将这个 JSON转换为 Markdown作为 API文档预览

TypeDoc 将 TypeScript 源代码中的注释转换为呈现的 HTML 文档或 JSON 模型。它是可扩展的并且支持多种配置。可作为 CLI 或节点模块使用。

Tsdoc 是一项标准化 TypeScript代码中使用的文档注释的提议，以便不同的工具可以提取内容而不会被彼此的标记混淆。

[jaywcjlove]

• v5 的开发计划 #717

• 组件文档放到组建包中（npm/github）中预览正常
• 国际化，国际化文件分两部分：
  • 一部分网站中的文本国际化
  • 组件文档部分国际化（README.md, README.jo.md,README.en.md，初步设计，是否有更佳方法）
• 组件中的示例，支持在线预览（可以放弃实时编辑，因为打包体积太大）
• 组件 API 文档支持自动生成到 README.md 中，可以研究一下 @microsoft/api-extractor，或者有更优秀的想发。