feat(core): support automatic generate api docs #OSP-230 (#294)

.docgenirc.js

@@ -46,6 +46,7 @@ module.exports = {
             rootDir: './packages/a-lib',
             include: ['common'],
             exclude: '',
+            apiMode: 'compatible',
             categories: [
                 {
                     id: 'general',

packages/a-lib/button/button.component.ts

@@ -1,5 +1,8 @@
 import { Component, OnInit, HostBinding, Input, ElementRef } from '@angular/core';
 
+/**
+ * Button 2
+ */
 @Component({
     selector: 'alib-button,[alibButton]',
     template: '<ng-content></ng-content>'
@@ -8,6 +11,11 @@ export class AlibButtonComponent implements OnInit {
     @HostBinding(`class.dg-btn`) isBtn = true;
 
     private type: string;
+
+    /**
+     * Button Type: `'primary' | 'secondary' | 'danger'`
+     * @default primary
+     */
     @Input() set alibButton(value: string) {
         if (this.type) {
             this.elementRef.nativeElement.classList.remove(`dg-btn-${this.type}`);
@@ -16,6 +24,11 @@ export class AlibButtonComponent implements OnInit {
         this.elementRef.nativeElement.classList.add(`dg-btn-${this.type}`);
     }
 
+    /**
+     * Button Size
+     */
+    @Input() alibSize: 'xs' | 'sm' | 'md' | 'lg' = 'xs';
+
     constructor(private elementRef: ElementRef<HTMLElement>) {}
 
     ngOnInit(): void {}

packages/a-lib/foo/foo.component.ts

@@ -1,12 +1,30 @@
-import { Component, OnInit } from '@angular/core';
+import { Component, Input, OnInit, Output, EventEmitter } from '@angular/core';
 
+/**
+ * Foo Component
+ */
 @Component({
     selector: 'alib-foo',
-    template: `<ng-content></ng-content>
+    template: `
+        <ng-content></ng-content>
     `
 })
 export class AlibFooComponent implements OnInit {
+    /**
+     * Type is foo
+     * @type string
+     */
+    @Input() alibType: 'primary' | 'secondary';
+
+    /**
+     * Close event when foo close
+     * @type string
+     */
+    @Output() alibClose = new EventEmitter<string>();
+
     constructor() {}
 
-    ngOnInit(): void {}
+    ngOnInit(): void {
+        this.alibClose.emit('hello');
+    }
 }

packages/a-lib/layout/layout.component.ts

@@ -1,4 +1,4 @@
-import { Component, OnInit, HostBinding } from '@angular/core';
+import { Component, OnInit, HostBinding, Input } from '@angular/core';
 
 @Component({
     selector: 'alib-layout',
@@ -9,6 +9,11 @@ import { Component, OnInit, HostBinding } from '@angular/core';
 export class AlibLayoutComponent implements OnInit {
     @HostBinding(`class.alib-layout`) isLayout = true;
 
+    /**
+     * Direction `vertical`
+     */
+    @Input() thyDirection: 'vertical' | 'horizontal';
+
     constructor() {}
 
     ngOnInit(): void {}

packages/cli/test/build.spec.ts

@@ -33,7 +33,7 @@ describe('#cli', () => {
             config: {
                 ...config,
                 skipSite: true
-            }
+            } as unknown
         });
         await docgeni.run();
         const expectConfig = { ...DEFAULT_CONFIG, ...config };

packages/core/src/builders/library-builder.spec.ts

@@ -1,14 +1,14 @@
 import { toolkit } from '@docgeni/toolkit';
 import { DocgeniContext } from '../docgeni.interface';
-import { HostWatchEvent, HostWatchEventType, normalize, resolve } from '../fs';
-import { createTestDocgeniContext, DEFAULT_TEST_ROOT_PATH, FixtureResult, loadFixture } from '../testing';
+import { HostWatchEventType, normalize, resolve } from '../fs';
+import { createTestDocgeniContext, DEFAULT_TEST_ROOT_PATH, FixtureResult, loadFixture, NgParserSpectator } from '../testing';
 import { LibraryBuilderImpl } from './library-builder';
 import { normalizeLibConfig } from './normalize';
 import * as systemPath from 'path';
-import { ChannelItem, NavigationItem } from '../interfaces';
-import { ASSETS_API_DOCS_RELATIVE_PATH, ASSETS_EXAMPLES_HIGHLIGHTED_RELATIVE_PATH, ASSETS_OVERVIEWS_RELATIVE_PATH } from '../constants';
-import { Observable, of } from 'rxjs';
+import { NavigationItem } from '../interfaces';
+import { of } from 'rxjs';
 import { LibraryBuilder, LibraryComponent } from '../types';
+import { DefaultNgParserHost, NgParserHost, ts, NgDocParser, DefaultNgParserHostOptions, NgDocParserOptions } from '@docgeni/ngdoc';
 
 class LibraryBuilderSpectator {
     components: LibraryComponent[];
@@ -294,6 +294,62 @@ describe('#library-builder', () => {
         });
     });
 
+    it('should create ngDocParser with automatic api mode', async () => {
+        library.apiMode = 'automatic';
+        const ngParserSpectator = new NgParserSpectator();
+
+        const tsconfig = resolve(libDirPath, 'tsconfig.lib.json');
+        context.host.writeFile(tsconfig, '{includes: []}');
+        const libraryBuilder = new LibraryBuilderImpl(context, library);
+        expect(libraryBuilder.getNgDocParser()).toBeFalsy();
+        ngParserSpectator.notHaveBeenCalled();
+        await libraryBuilder.initialize();
+        ngParserSpectator.toHaveBeenCalled({
+            tsConfigPath: tsconfig,
+            rootDir: libDirPath,
+            watch: true
+        });
+        expect(libraryBuilder.getNgDocParser()).toEqual(ngParserSpectator.mockNgParser);
+    });
+
+    it('should create ngDocParser with compatible api mode', async () => {
+        library.apiMode = 'compatible';
+        const ngParserSpectator = new NgParserSpectator();
+
+        const tsconfig = resolve(libDirPath, 'tsconfig.lib.json');
+        context.host.writeFile(tsconfig, '{includes: []}');
+        const libraryBuilder = new LibraryBuilderImpl(context, library);
+        expect(libraryBuilder.getNgDocParser()).toBeFalsy();
+        ngParserSpectator.notHaveBeenCalled();
+        await libraryBuilder.initialize();
+        ngParserSpectator.toHaveBeenCalled({
+            tsConfigPath: tsconfig,
+            rootDir: libDirPath,
+            watch: true
+        });
+        expect(libraryBuilder.getNgDocParser()).toEqual(ngParserSpectator.mockNgParser);
+    });
+
+    it('should rebuild component when watch api docs', async () => {
+        library.apiMode = 'compatible';
+        const ngParserSpectator = new NgParserSpectator();
+
+        const tsconfig = resolve(libDirPath, 'tsconfig.lib.json');
+        context.host.writeFile(tsconfig, '{includes: []}');
+        const libraryBuilder = new LibraryBuilderImpl(context, library);
+        expect(libraryBuilder.getNgDocParser()).toBeFalsy();
+        ngParserSpectator.notHaveBeenCalled();
+        await libraryBuilder.initialize();
+        const compileSpy = spyOn(context, 'compile');
+        expect(compileSpy).not.toHaveBeenCalled();
+        ngParserSpectator.fakeFileChange(resolve(libDirPath, './button/button.component.ts'));
+        expect(compileSpy).toHaveBeenCalledWith({
+            libraryBuilder: libraryBuilder,
+            libraryComponents: [libraryBuilder.components.get(resolve(libDirPath, 'button'))],
+            changes: []
+        });
+    });
+
     describe('watch', () => {
         it('should watch components', async () => {
             const libraryBuilder = new LibraryBuilderImpl(context, library);

packages/core/src/builders/library-builder.ts

@@ -1,24 +1,19 @@
 import { DocgeniContext } from '../docgeni.interface';
 import { CategoryItem, ChannelItem, ComponentDocItem, ExampleSourceFile, Library, LiveExample, NavigationItem } from '../interfaces';
 import { toolkit } from '@docgeni/toolkit';
-import {
-    ASSETS_API_DOCS_RELATIVE_PATH,
-    ASSETS_EXAMPLES_HIGHLIGHTED_RELATIVE_PATH,
-    ASSETS_OVERVIEWS_RELATIVE_PATH,
-    SITE_ASSETS_RELATIVE_PATH
-} from '../constants';
 import { ascendingSortByOrder, getItemLocaleProperty } from '../utils';
 
-import { AsyncSeriesHook, SyncHook } from 'tapable';
 import { LibraryComponentImpl } from './library-component';
 import { HostWatchEventType, relative, resolve } from '../fs';
 import { EmitFile, EmitFiles, LibraryBuilder, LibraryComponent } from '../types';
 import { FileEmitter } from './emitter';
+import { ts, NgDocParser, DefaultNgParserHost } from '@docgeni/ngdoc';
 
 export class LibraryBuilderImpl extends FileEmitter implements LibraryBuilder {
     private absLibPath: string;
     private localeCategoriesMap: Record<string, CategoryItem[]> = {};
     private componentsMap = new Map<string, LibraryComponent>();
+    private ngDocParser: NgDocParser;
 
     constructor(private docgeni: DocgeniContext, public lib: Library) {
         super();
@@ -29,6 +24,10 @@ export class LibraryBuilderImpl extends FileEmitter implements LibraryBuilder {
         return this.componentsMap;
     }
 
+    public getNgDocParser() {
+        return this.ngDocParser;
+    }
+
     public async initialize(): Promise<void> {
         this.buildLocaleCategoriesMap(this.lib.categories);
 
@@ -56,6 +55,36 @@ export class LibraryBuilderImpl extends FileEmitter implements LibraryBuilder {
             components.push(component);
             this.componentsMap.set(absComponentPath, component);
         });
+
+        this.watch();
+        await this.initializeNgDocParser();
+    }
+
+    private async initializeNgDocParser() {
+        if (this.lib.apiMode !== 'manual') {
+            const tsConfigPath = resolve(this.docgeni.paths.cwd, resolve(this.lib.rootDir, 'tsconfig.lib.json'));
+            if (await this.docgeni.host.exists(tsConfigPath)) {
+                const parserHost = DefaultNgParserHost.create({
+                    tsConfigPath: tsConfigPath,
+                    watch: this.docgeni.watch,
+                    rootDir: this.docgeni.paths.getAbsPath(this.lib.rootDir),
+                    watcher: (event, filename) => {
+                        const changes: LibraryComponent[] = [];
+                        for (const [key, component] of this.components) {
+                            if (filename.includes(key)) {
+                                changes.push(component);
+                            }
+                        }
+                        this.docgeni.compile({
+                            libraryBuilder: this,
+                            libraryComponents: changes,
+                            changes: []
+                        });
+                    }
+                });
+                this.ngDocParser = this.lib.ngDocParser = NgDocParser.create({ ngParserHost: parserHost });
+            }
+        }
     }
 
     public async build(components: LibraryComponent[] = Array.from(this.componentsMap.values())): Promise<void> {