Link Search Menu Expand Document
云研发：研发即代码

DSL@core：文档代码化

目录

  1. 如何实现一个文档代码化系统？
    1. 1. 确立关键因素
    2. 2. 实现一个 MVP
    3. 3. 扩展语法
    4. 3.1 重写 markdown 渲染器
    5. 4. 发布这个项目

文档代码化，将文档以类代码的领域特定语言的方式编写，并借鉴软件开发的方式（如源码管理、部署）进行管理。它可以借助于特定的工具进行编辑、预览、查看，又或者是通过专属的系统部署到服务器上。面向非技术人员的文档代码化的一种常见架构模式是：编辑-发布-开发分离』，

一个易于维度的文档化系统，它应该是：

  • 一个技术决策发生的时间和架构改变，对应的修改人
  • 回溯所有的技术决策，从中整理出架构发展过程
  • 所有的决策都是记录在版本控制系统中，可恢复
  • 易于管理和维护

它具备这么一些特征：

  • 使用标记语言编写内容。如 markdown
  • 可通过版本控制系统进行版本控制。如 git
  • 与编程一致的编程体验（除了内容写不了测试）

而一个高效的文档代码化系统，还具备这么一些特征：

  • 持续部署，即修改完内容可自动发布。
  • 与特定的形式组织内容索引。如以知识库的形式来组织内容。
  • 特定的文本格式。如架构决策记录、静态内容生成，以用于以提供更好的用户体验
  • 可支持 REST API。以通过编辑器来修改内容
  • 可以支持多种方式的输出。如网站标准 HTML，又或者是 Docx、Latex 等
  • 支持编辑、校对工作流
  • 支持搜索
  • 多人协作

而事实上，大部分的团队并不需要上述的高级功能，而且它们都已经有了成熟的方案。

如何实现一个文档代码化系统？

事实上，我们在四个引子中标明了我们所需要的要素：

  1. 使用格式化的文档
  2. 借助静态站点生成技术来发布系统
  3. 通过定制标记语言扩充能力
  4. 面向非技术人员实现编辑器

设计一个标记语言及其扩展语法，然后实现它即可。

1. 确立关键因素

考虑到我和我的同事们最近实现了这么一个系统，我还是忍受一下手的痛楚，简单说一下怎么做这样一个系统。我们所考虑的主要因素是：

  • 图表渲染
  • 流程图渲染
  • 可视化展示

因为由 DSL 转换成的图表易于修改，并且可以索引。于是乎，我们：

  1. 通过 markdown 的 Code 语法来扩充这些能力
  2. 使用 markdown 的 table 和 list 来提供数据
  3. 使用 D3.js 来支持流程图绘制
  4. 使用 Echarts 来进行图表绘制
  5. 尽量使用 SVG 图片
  6. ……

2. 实现一个 MVP

我们使用 Angular + GitHub，快速实现了一个 MVP：

  1. 我们使用 Git 作为数据库.它就可以实现多人协作的目的，并且可以追踪所有的变化
  2. 我们使用 GitHub Pages 作为服务器。只要一修改文档或者代码，就会部署最新的文档。
  3. 我们使用 marked.js，它可以让我们快速扩展语法。
  4. 使用 textarea 结合 markdown 制作了一个简易的编辑器。

随后，我们在这个基础上进行了快速的迭代。

3. 扩展语法

我们使用了 markdown 的 code 作为图表的 DSL，扩展了这么一些语法：

  • echarts。直接渲染 Echarts 图表
  • mindmap。Markdown List 转为思维导图
  • radar。Markdown List 转为雷达图
  • process-table。带流程的图表
  • process-step。另外一种带流程的图表
  • pyramid。金字塔图形
  • quadrant。四象限图
  • class。直接调用 CSS 的 class
  • graphviz。使用 Dot 渲染图片
  • mermaid。使用 mermaid 可视化
  • webcomponents。调用 WebComponents 组件
  • toolset。调用 Toolset 相关的组件
    • slider。权衡滑块
    • line-chart。表图

所以，对于使用者来说，只需要编写下面的代码：

```radar
 - 质量成熟度评估模型
  - 质量内建: 3 -> 4
  - 优化业务价值: 2 -> 2
  - 质量统一，可视化: 1 -> 5
  - 全员参与: 3 -> 4
  - 快速交付: 4 -> 5
  - 测试作为资产: 2 -> 3
  - 快速反馈: 5 -> 5

config: {"legend": ["当前", "未来"]}
\```

就可以生成对应的图表。我们还通过 config 来输入 JSON，进行一定的懒惰化处理（不要累死自己）。

3.1 重写 markdown 渲染器

我们在这个过程中，遇到的最大的挑战是，随着我们对 markdown 语法的不断扩充，相关的代码已经变成了一坨大泥球。所以，我们不得不重写了这部分代码：

  1. 借助于 marked.js 的 lexer 解析出 token
  2. 根据 token 修改生成新的 token
  3. 遍历新生成的 token，渲染出元素
  4. 结合虚拟滚动，解决性能问题

已经开源在 GitHub，并发布对应的 npm 包：@ledge-framework/render。

4. 发布这个项目

我们已经在 GitHub 上发布了这个文档化系统，你可以参与到其中的使用和开发。

GitHub：https://github.com/phodal/ledge

项目首页：https://devops.phodal.com/