@boundstate/ng-docs

ng-docs

Docs generator for Angular libraries.

Quick start

$ npm i -D @boundstate/ng-docs @boundstate/ng-docs-cli

The following assumes you use Angular CLI to generate a library, and your workspace is setup like this:

├── projects/
│   └── my-lib/     (library)
├── src/            (app)

Use the CLI to generate docs for your library and write the output to your app. Add this to your build scripts (e.g. package.json) so that it's run before ng serve and ng build commands:

ng-docs --base=projects/my-lib src/app/docs.ts

Modify your app to display the docs:

import {DocsModule} from '@boundstate/ng-docs';

import {docs} from './docs'; // generated docs

@Component({
  selector: 'app-root',
  template: `<ngd-app></ngd-app>`,
})
export class AppComponent {}

@NgModule({
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    DocsModule.forRoot(docs),
  ],
  declarations: [AppComponent],
  bootstrap: [AppComponent],
})
export class AppModule {}

Demos

You can include demos in your app by creating demo modules and passing them to DocsModule.forRoot():

DocsModule.forRoot(docs, {demos: [
  HelloWorldDemoModule,
]}),

Your demo modules must use the @Demo() decorator:

import {Component, NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';
import {Demo} from '@boundstate/ng-docs';

import {MyLibModule} from 'my-lib';

@Component({template: '<app-hello-world color="purple"></app-hello-world>'})
export class HelloWorldDemoComponent {}

@Demo({
  id: 'hello-world',
  name: 'Hello World',
  related: ['HelloWorldComponent'],
})
@NgModule({
  imports: [
    MyLibModule,
    RouterModule.forChild([{path: '', component: HelloWorldDemoComponent}]),
  ],
  declarations: [HelloWorldDemoComponent],
})
export class HelloWorldDemoModule {}

Known issues

Demo modules will not load in AOT builds: https://github.com/angular/angular-cli/issues/4192

Workaround: disable AOT

Development

Running the demo

$ npm run build:lib
$ npm start