Darkeering Blog

Angular 使用 Docgeni 搭建组件库文档

2023-07-17T14:55:42.000Z

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: 在类别中的排序
是特定的 Demo 组件
是全部的 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
```

Welcome

2021-08-26T00:00:00.000Z

Docusaurus blogging features are powered by the blog plugin.

Simply add Markdown files (or folders) to the blog directory.

Regular blog authors can be added to authors.yml.

The blog post date can be extracted from filenames, such as:

2019-05-30-welcome.md
2019-05-30-welcome/index.md

A blog post folder can be convenient to co-locate blog post images:

The blog supports tags as well!

And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.

MDX Blog Post

2021-08-01T00:00:00.000Z

Blog posts support Docusaurus Markdown features, such as MDX.

tip

Use the power of React to create interactive blog posts.

<button onClick={() => alert('button clicked!')}>Click me!</button>

Long Blog Post

2019-05-29T00:00:00.000Z

This is the summary of a very long blog post,

Use a comment to limit blog post size in the list view.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

First Blog Post

2019-05-28T00:00:00.000Z

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

Darkeering Blog

Angular 使用 Docgeni 搭建组件库文档

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

手动安装 Docgeni​

添加组件​

添加展示文档和 example 组件​

起服务​