0.1.24 • Published 4 years ago

@alicloud/console-components-lib-publisher v0.1.24

Weekly downloads
2
License
MIT
Repository
-
Last release
4 years ago

name: lib-publisher zhName: 文档构建发布 sort: 3 tags: dev-kit: true

documentation: true

@alicloud/console-components-lib-publisher

@alicloud/console-components-lib-publisher是 console-components 提供的物料开发者工具包。 它提供了以下脚本,来辅助物料开发、协作:

  • cc-extract-api 它做了以下 3 件事情:
    • 使用api-extractor,读取lib/index.d.ts(即tsc的输出),提取 ts 代码中的类型、注释信息。输出到cc-dev-out/api-extractor/目录。
    • 然后,dev-kit/api-documenter会将上述输出信息加工成 json 数据,作为 API 文档的数据。输出到cc-dev-out/api-json/目录。因此,业务组件的 API 文档由源码转化而成,而不是人工维护,避免文档腐化
    • lib/index.d.ts为入口,将.d.ts声明文件打包(类似于 webpack 打包 js 模块),输出到cc-dev-out/index.d.ts,在此过程中,被声明为@internal@alpha的 ts 类型、接口成员会被过滤掉。你可以利用这一点来避免不稳定的 ts 接口暴露给用户,提高封装性。详见api-extractor 文档
  • cc-build-doc 将 markdown 文档打包成一个 js bundle。
    • 构建成 js bundle 的好处是便于分发和扩展。各种基于 markdown 的扩展(demo 嵌入、ts Interface 渲染、图片内联、目录生成)在构建阶段就已经被处理完毕,文档站点无需关注文档功能的编译和实现,文档站点可以将一篇文档当做一个普通 React 组件来加载、渲染。未来我们向 markdown 语法加入更多扩展的时候,文档站点没有感知。

      详细的文档扩展能力说明,请参考 👉文档能力

    • 一般的用法是将 markdown 构建成 bundle 以后,放在 npm 包中一起发布,文档站点通过 npm cdn(比如 unpkg)来加载文档。
  • cc-doc-local-dev 本地开发、预览。
    • 既然已经可以将 markdown 文档打包成一个 js bundle,自然也就很容易实现本地开发模式(使用webpack-dev-server)。在这个模式下你可以快速预览渲染后的文档。我们会监听 markdown 文件的变更、src 代码的变更、demo 代码的变更,并自动刷新。

      目前,对 Typescript Interface 代码的修改,不会导致文档中渲染的 Interface 表格的热刷新。需要重新执行npm run prepare && npm run doc:local-dev

  • cc-publish-preview 将当前的物料发布成一个预览包。
    • 预览包包括物料本身的运行代码,以及物料的文档 bundle
    • 通过临时 npm 账号将当前 package 发布到@cc-dev-kit-test/${实际包名}
    • 预览包发布成功以后,你会立刻得到一个 URL 分享链接。将 URL 分享给你的 UI 评阅者,评阅者用浏览器打开就能看到当前物料的文档。得益于文档的 Codesandbox Demo 能力、API 文档能力,这份文档能够快速地让评阅者了解、试用你开发的物料,无需切换代码分支、启动开发服务器等耗时的操作。
    • 请阅读 👉文档评审

以上脚本工具都在物料包根目录(即 package.json 所在的目录)运行。使用他们的项目范例:最小示例Wind 物料的使用方式

本工具包只负责开发期的信息提取、构建、发布;运行时的加载、样式和功能放在@alicloud/console-components-lib-documenter包中。

为什么要选择打包文档

站点与文档扩展能力解耦

为了增强文档的表现能力和阅读体验,我们基于普通 Markdown 文档做了很多扩展。你编写的文档不局限于文本、HTML 的表现能力,它还能嵌入外部的非文本内容(提取源码中的 Interface 并渲染到文档上)、交互性内容(用户可编辑、试验的 Demo)。我们还会解析文档结构,自动生成文档目录。

如果将这些扩展交给文档站点来实现,会出现两个问题:

  • 单一职责:文档站点就需要做很多文档粒度的事情(解析文档文本中的扩展语法指令、根据指令对文档进行转换、渲染),代码混杂在一起,无法专注于文档编排的本职工作。
  • 文档不可复用:只有我们自己的文档站点能够渲染这种文档,因为一般的站点没有实现这些文档扩展。举个例子,目前 xconsole 的站点就有嵌入 console-components 文档的需求,因为 console-components 是 xconsole 设计规范的官方实现。

这就是为什么我们要把文档能力从站点解耦出来,提炼出@alicloud/console-components-lib-publisher工具包,它负责在开发构建期间辅助文档的编写和发布。与之对应的,@alicloud/console-components-lib-documenter负责在运行期间辅助文档的加载和渲染。

这个工具究竟实现了哪些文档功能,已经在 👉文档能力进行了详细说明。本篇文档只阐述文档打包相关的重要特性。

解耦以后,@alicloud/console-components-lib-publisher在构建期解析文档文本,根据其中的指令对文档进行转换、渲染,输出成 JavaScript bundle,它导出一个 React 组件。文档站点只需要加载这个 bundle,然后像渲染普通 React 组件一样,将它渲染出来,就能够让用户看到表现形式丰富的文档。文档站点不需要知道这些表现能力是如何实现,专注于站点应用的实现,比如导航目录编排、页面搜索、文档分类等。

@alicloud/gatsby-theme-console-doc就是这样一个文档站点框架,帮助开发者快速配置出一个功能丰富的文档站点。本站点就是使用这个框架来配置出来的。

另一方面,其他文档站点(即使不使用我们提供的站点框架)也能渲染我们的文档,因为它已经被转换成一个普通的 React 组件。

文档可动态加载

通过加载 js bundle 的方式来加载文档,意味着你无需为文档站点实现任何后端数据服务。 你将文档站点构建好以后,部署到 cdn(比如使用免费的 unpkg)。静态站点在运行时从 cdn 加载文档 bundle。 当文档更新以后,你只需要重新构建、部署 cdn,你的文档站点就会加载到最新的文档,无需重新构建发布。 这样就在保持站点静态化(不依赖后端数据服务)的同时,做到了文档站点的实时更新。

承载本地图片

我们书写 markdown 文档的时候经常有一个痛点:由于 markdown 是文本格式,它不能直接承载图片,因此往往需要借助图床。但是图床嵌入图片的方式会遇到以下困扰:

  • 操作太麻烦:上传到图床、拷贝 url、在 markdown 中插入图片![altText](https://url.com)
  • 很难找到可靠(且免费)的图床,大部分免费的平台无法保证图片长期有效。如果图床突然删除了你的图片,你很可能再也找不回来(如果你自己没有备份的话)
  • 便携性(portability)差:文档与平台绑定。虽然很多文档、博客平台提供了图床(比如语雀),但是把图片放在平台图床会让你的文档与图片在存储上分离,变得难以迁移

于此相反的是 Word 文档格式、PDF 格式,它们本身是二进制格式,能直接承载图片,不会有上述的困扰。

@alicloud/console-components-lib-publisher选择了 js bundle 作为文档的分发形式。js bundle 是一种非常便携的分发格式(类似于 PDF 文档)。利用 webpack 的一些 loader,它可以将本地的图片打包到 js bundle 中。因此,你的文本、demo 代码、图片等资源都一起存在本地仓库,本地仓库是"single source of truth",可以通过 git 来存管和追踪。

.开头的 url 视为相对路径,指向本地图片,会被打包到 js bundle 中(data-url 编码)。并且我们自动帮你做了图片压缩,以便减小 bundle size。 示例:![aliyun](./assets/aliyun.png)

其他的 url 视为普通外链 url,不会被打包。 示例:![aliyun](https://img.alicdn.com/tfs/TB1Ly5oS3HqK1RjSZFPXXcwapXa-238-54.png)