关于开源软件:Docgeni开箱即用的-Angular-组件文档工具

本文由 Worktile 产品研发部负责人 @徐海峰分享

如果说 2020 年惟一的遗憾是什么，那就是没有把 Docgeni 开源进来，尽管代码早就公开了。然而脚手架和文档始终没有欠缺，再加上整个实现还是比拟毛糙，所以始终没有对外发表，从 2020 年 3 月 26 日提交的第一行代码到当初一年多了，明天在 2021-05-20 的好日子正式发表开源并公布 1.0.0 版本。

Docgeni 是一款为 Angular 组件开发场景而生的文档工具，反对组件文档和一般的 Markdown 文档生成。

Docgeni 会主动依据目录构造和 FrontMatter 生成对应的文档导航、菜单和路由，同时反对配置一级导航和路由以满足自定义需要；另外，为了便于开发组件和展现组件 Example, Docgeni 反对在 Markdown 语法中导入 Example。

📦 开箱即用，让你疾速开启文档编写和组件开发
🏡 独立的 Angular 组件预览体验，蕴含：组件概览，示例，API
📋 对 Markdown 语法进行扩大，在文档中间接导入 Example
💻 多语言反对
🚀 两种模式以及多种格调反对

那么你必定会问：社区曾经有很多文档生成工具了，为什么又造一个轮子？

2018 年，咱们开始应用 Angular 搭建本人的组件库，通过了 2 - 3 年咱们的组件库曾经有 50+ 个组件了。那么对于组件库开发来说，文档和示例是十分重要的一环，咱们一开始也是和其余组件库一样间接在仓储中写一个 Demo 站点作为文档和示例展现，每当新增一个组件就须要在示例中新增这个组件对应的示例模块，示例组件等等，写组件示例和文档十分的繁琐，同时加上咱们 2019 年开始搭建业务组件库，意味着同样的示例根底性能我还要再次写一遍，特地麻烦，另外就是之前的文档站点很不业余，所以就开始寻找一款 Angular 组件开发生成文档和组件示例的工具。

寻找和钻研了很多组件文档生成工具，发现 React 和 Vue 框架的计划有很多，Angular 框架竟然没有一个开箱即用的组件文档的生成工具。大家比拟相熟的 Angular 组件库（比方：Material Design、ng-zorro-antd、ngx-bootstrap 等）都是在仓储外部搭建的示例站点，无奈间接被其余组件库复用，所以最终就萌发了咱们要本人写一个为 Angular 组件开发而生的文档工具的想法。

awesome-docgen 这个仓储列举出了咱们过后调研的一些文档生成工具，storybook 可能是惟一一个反对 Angular 框架的文档生成工具，然而它的展现状态和写法挺繁琐了，最终没有抉择应用它。

我在很多场合都表白过：Angular 是一款十分优良的前端框架，咱们也始终想回馈社区，然而 Angular 苦于一款开箱即用的组件库文档生成工具都没有，为了让 Angular 框架的生态更加凋敝，咱们决定将 Docgeni 开源，当然 Docgeni 目前并不欠缺，只是临时满足了咱们公司外部的根本需要，一些高级个性还未反对，咱们也会始终继续保护更新迭代。

对于文档工具，有以下三种类型：

一般文档：纯 Markdown 语法的文档，前后端通用，次要展现入门指南，配置阐明文档应用，这样的工具有无数个
组件文档：根本和前端框架绑定，展现组件的应用阐明，组件的参数，组件的示例（Examples）
API 文档：相似 Angular 官网的 API，当然大部分组件库是不须要这个性能的

Docgeni 同时反对一般文档和组件文档的生成，当然对于一些纯文档的场景，应用 Docgeni 只生成 Markdown 一般文档也是能够的。

这里简略介绍一下 Docgeni 相比拟其余组件文档生成工具的的差别点。

对于某个组件来说，分为概览、示例、API，三者独立离开，根本和 Material Design Components 保持一致。

反对full 和lite 两种模式，对于一些小的类库或者纯 Markdown 文档来说，可能并不需要头部导航，那么采纳 lite 模式无疑是最合适不过的。

默认主题头部导航背景色是红色，如果心愿和 Angular 官网一样的主题，能够设置 theme 为：angular，展示的成果如下：

如果在一个仓储中存在多个类库，比方 angular/components 中就蕴含 CDK 和 Components，那么 Docgeni 能够配置多个类库导航，别离为展现不同的类库，当然这种场景还是比拟少见的。

对于文档站点，用户须要自定义 Title，Scripts，Styles、Assets 等等，Docgeni 提供了 publicDir自定义index.html、assets、.browserslistrc、styles.scss 等性能，详情查看自定义站点。

如果自定义 public 能力还不足以满足自定义的需要，那么 Docgeni 还反对一个齐全自定义站点的模式，用户能够在自定义站点中加一些自定义的 Angular 模块，或者在根模块下注入一些全局内置的服务，齐全自定义示例站点只须要配置 siteProjectName: {siteName}，而后批改 AppModule 的代码如下：

import {NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';
import {BrowserModule} from '@angular/platform-browser';
import {DOCGENI_SITE_PROVIDERS, RootComponent} from './content/index';
import {DocgeniTemplateModule} from '@docgeni/template';
@NgModule({declarations: [],
    imports: [BrowserModule, DocgeniTemplateModule, RouterModule.forRoot([])],
    providers: [...DOCGENI_SITE_PROVIDERS],
    bootstrap: [RootComponent]
})
export class AppModule {constructor() {}}

同时须要把 src/app/content 和 src/assets 两个文件夹疏忽 git，能够在站点的 src 根目录创立 .gitignore 文件。

app/content
assets/content

批改 styles.scss 输出如下内容：

@import '~@docgeni/template/styles/index.scss';

执行以下的任意命令进行脚手架初始化。

$ npx @docgeni/cli init
# 或者 
$ docgeni init 
# 或者
$ ng add @docgeni/cli

应用 docgeni init 初始化须要全局装置 @docgeni/cli npm install -g @docgeni/cli
应用ng add @docgeni/cli 初始化须要全局装置 Angular CLI npm install -g @angular/cli

执行上述任意一个命令后将主动实现 docgeni 的初始化配置，包含生成配置文件、NPM 启动脚本、默认文档等工作。

第一步抉择文档站点模式: full 或者 lite(默认 lite)
第二步输出文档目录 (默认 docs)

初始化后，应用npm run start:docs 启动文档站点，浏览器关上http://127.0.0.1:4600 即可拜访。
Docgeni 初始化脚手架会自动检测并增加以后 Angular 我的项目中的类库，默认类库的组件没有编写文档和示例，所以不会展现，能够依照组件概览文档要求编写组件文档和示例，比方：咱们的组件根目录下有一个按钮组件，在 button 组件文件夹下创立一个doc/zh-cn.md 文档，输出如下内容：

---
title: 按钮
---

## 何时应用
按钮用于开始一个即时操作。

展现成果如下:

除此之外 Docgeni 还提供了一个模板仓储：https://github.com/docgeni/docgeni-template，能够疾速创立一个带有文档的 Angular 组件类库。

更多详情参考疾速上手文档。

开源不是说 Docgeni 曾经成熟和稳固了，只是初步具备了一个最小化的可用版本，同时开源也是一个新的终点和开始，心愿有更多的 Angular 用户应用并反馈，逐步欠缺它，以下是目前已知的路线图：

接入 Algolia 反对搜寻性能
提供更多的内置组件（Alert、Label 等）
反对服务端 ssr 或者预渲染
更加敌对的 CLI 进度提醒
自定义首页
自定义底部
内部独立的示例展现
左侧菜单反对折叠
文档展示优化（记录文档的贡献者、最初一次生成工夫、上一篇下一篇）
toc 配置多种模式（左侧菜单显示、右侧内容显示和暗藏）
依据正文主动生成组件 API
集成第三方示例工具（比方：codesandbox）
….

欢送关注和奉献。https://github.com/docgeni/docgeni

最初打个广告，举荐研发团队应用：Worktile 团队打造的比 Jira 更好用的智能化研发管理工具 PingCode，25 人及以下还收费，太没天理了。

PingCode 官网

关于开源软件:Docgeni开箱即用的-Angular-组件文档工具

什么是 Docgeni？

个性

动机

文档工具的分类

Docgeni 的特点

独立的组件的预览体验

两种模式的反对

两种主题的反对

反对多类库

弱小的自定义能力

疾速上手

最初