Angular 使用 Docgeni 搭建组件库文档

July 17, 2023

tip

npm i -g @angular/cli@15.2.8

使用 Angular 脚手架生成一个组件库架子

生成一个空的项目

ng new ng-darui --create-application=false

生成一个 library 项目
```
ng g lib ng-darui --prefix=dar
```

删除多余组件和文件，并移动文件，最终目录是这样

├─ng-darui
|    ├─ng-package.json
|    ├─package.json
|    ├─public-api.ts
|    ├─README.md
|    ├─tsconfig.lib.json
|    ├─tsconfig.lib.prod.json
|    ├─tsconfig.spec.json

修改配置文件

angular.json
- "sourceRoot": "projects/ng-darui/src",
+ "sourceRoot": "projects/ng-darui",

ng-package.json
- "entryFile": "src/public-api.ts"
+ "entryFile": "public-api.ts"

tsconfig.json
  "paths": {
-   "ng-darui": [
-     "dist/ng-darui"
+   "ng-darui/*": [
+     "projects/ng-darui/*"
    ]
  },

手动安装 Docgeni

下载依赖包
```
npm i @docgeni/cli @docgeni/template -D
```

添加 .docgenirc.js 配置

.docgenirc.js
/**
 * @type {import('@docgeni/core').DocgeniConfig}
 */
module.exports = {
  mode: "lite",
  title: "ng-darui",
  description: "",
  docsDir: "docs",
  navs: [
    null,
    {
      title: "Components",
      path: "components",
      lib: "ng-darui",
      locales: {},
    },
  ],
  libs: [
    {
      name: "ng-darui",
      abbrName: "dar",
      rootDir: "projects/ng-darui",
      include: [""],
      apiMode: "automatic",
      categories: [
        {
          id: "general",
          title: "通用",
          locales: {
            "en-us": {
              title: "General",
            },
          },
        },
      ],
    },
  ],
};

添加概述文档（没有它，项目起不来）

mkdir docs && echo 'Hello Docgeni!' > docs/getting-started.md

tsconfig.json 中添加/修改 path

tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "ng-darui/*": ["projects/ng-darui/*"]
    }
  }
}

添加组件

通过 Angular 脚手架添加组件
之前修改了 angular.json 中的 sourceRoot 之后，默认生成时在 lib 目录下面，所以需要返回一个层级
```
ng g m ../button --project=ng-darui

ng g c ../button --project=ng-darui --module=button
```

修改组件文件

修改 button.module.ts

button.module.ts
  @NgModule({
    declarations: [
      ButtonComponent
    ],
    imports: [
      CommonModule
    ],
+   exports: [
+     ButtonComponent
+   ]
  })
  export class ButtonModule { }

在 button 文件夹下面添加 index.ts

button > index.ts
export * from "./button.component";
export * from "./button.module";

在 public-api.ts 中添加
public-api.ts
```
export * from "./button";
```

添加展示文档和 example 组件

先展示最终的目录情况

├─doc
|  └en-us.md
├─examples
|    ├─basic
|    |   ├─basic.component.css
|    |   ├─basic.component.html
|    |   └basic.component.ts
├─button.component.css
├─button.component.html
├─button.component.spec.ts
├─button.component.ts
├─button.module.ts
├─index.ts

basic 组件就是展示的 Demo 框框里面的东西

basic.component.html
<dar-button></dar-button>

basic 组件用的是 Angular 的独立组件

basic.component.ts
import { CommonModule } from "@angular/common";
import { Component } from "@angular/core";
import { ButtonModule } from "ng-darui/button";

@Component({
  selector: "dar-button-basic-example",
  templateUrl: "./basic.component.html",
  styleUrls: ["./basic.component.css"],
  standalone: true,
  imports: [CommonModule, ButtonModule],
})
export class DarButtonBasicExampleComponent {
  constructor() {}
}

给 Button 组件添加 Api

button.component.ts
/**
  * Button Type: `'primary' | 'secondary' | 'danger'`
  * @description 按钮类型
  * @default primary
  * @type 'primary' | 'secondary' | 'danger'
  */
@Input('type') type: string = 'primary'

en-us.md 就是组件的概述
info
category: 这个组件在哪个类别里面，就是之前在 .docgenirc.js 文件中定义的
name: 组件的名字，如果改成 aaa，那么 example 的 name 就应该是 dar-aaa-basic-example
order: 在类别中的排序
<example name="dar-button-basic-example" /> 是特定的 Demo 组件
<examples />是全部的 Demo 组件都展示
en-us.md
```
---
category: general
title: Button
name: button
order: 1
---

这是单个
<example name="dar-button-basic-example" />

这是全部
<examples />
```

起服务

添加脚本

package.json
"scripts": {
  "start:docs": "docgeni serve --port 4600",
  "build:docs": "docgeni build"
},

.gitignore 忽略文件
起服务会生成临时文件，需要在.gitignore 中忽略这些临时文件
```
.docgeni/site
```

使用 Angular 脚手架生成一个组件库架子​

手动安装 Docgeni​

添加组件​

添加展示文档和 example 组件​

起服务​

使用 Angular 脚手架生成一个组件库架子

手动安装 Docgeni

添加组件

添加展示文档和 example 组件

起服务