ngx-doc-gen 📚

Automatically generate your library's API docs using Angular CLI or NX.

Credits

The initial spark was given by the folks from the Angular team (angular/components) who are using a perfectly working base implementation on documentation generation utilizing Dgeni.

Props to those who deserve it 🍻

Most of the code as well as the templates and styles originate from their repository.

📕 Installation / Configuration

Using NX:

npm install --save-dev ngx-doc gen
nx generate ngx-doc-gen:configure

Using Angular CLI

ng add ngx-doc-gen

Those calls will add a doc-gen target similiar to the build one to all touched library projects.

🤖 Generation

Using NX:

nx run <project>:doc-gen

Using Angular CLI:

ng doc-gen <project>

While generation is running ngx-doc-gen will scan the given library for its entrypoints - or entrypoint if there is just one - and extract the public API. The heavy lifting is done by Dgeni.

After extraction it categorizes your API in like modules, services, etc. - just like its done when looking at the Angular Material docs - and processes specific templates.

After everything is done ngx-doc-gen will output an HTML file per entrypoint into the output directory (read on for configuration).

📖 Configuration options (configure / ng add)

--projects

• Type: string[]
• Defines the libraries which should get configured for documentation generation
• Will throw an error if a project is listed which does not exist in the workspace
• Default: []
• Example:
  • NX: ng generate ngx-doc-gen:configure --projects lib-a,lib-b
  • Angular CLI: ng add ngx-doc-gen --projects lib-a,lib-b
  • Both examples will only configure the given library projects

If not provided or left empty - the default - configure (Generator) and ng add (Angular CLI) will scan your workspace for all buildable library projects and condigures them for documentation generation.

⚙️ Generation options

Per CLI

--log-level

• Type: 'error' | 'warn' | 'debug' | 'verbose'
• Defines the log level Dgeni uses while generation
• Default: 'warn'

--output-path

• Type: Path
• Defines the output path for the generated files (relative to working directory)
• Default: 'docs'

--exclude-base

• Type: string[]
• Defines base clases to exclude from generation
• Default: []
• Example:
  • Your API contains a service extending Observable which would include members like subscribe() in your documentation. This could be prevented as follows:
  • --exclude-base Observable

--docs-public

• Type: string
• Tag to enforce documentation of usually private symbols. Only applies to symbols at least exported.
• Default: docs-public

--docs-private

• Type: string,
• Tag to explicitly hide symbols from documentation.
• Default: docs-private

--breaking-change

• Type: string,
• Tag indicating the version with which a deprecated symbol will get removed.
• Default: breaking-change

Per workspace config (angular.json / workspace.json / project.json)

Every CLI parameter can also be bound to the doc-gen target in your workspace configuration so you don't have to pass them on every CLI call - see example below.

Some parameters can be passed by configuration only.

customTags

• Type: TagDefinition[]
• Configures tag definition for the Dgeni JSDoc processor not supported by JSDoc.
• Default: []

| Property | Type | Description | |---------------|-----------|-------------| | name | string | Name of the tag (excluding the @) | | docProperty? | string | Property where the tag information should be attached to. | | multi? | boolean | Whether multiple instances of the tag can be used in the same comment. | | required? | boolean | Whether this tag is required for all API documents. |

// Example given for a project.json
...
"<project>": {
  "targets": {
    "doc-gen": {
      "executor": "ngx-doc-gen:generate",
      "options": {
        "logLevel": "verbose",
        "outputPath": "./docs/libs/<project>",
        "excludeBase": [
          "Observable"
        ],
        "customTags": [
          {
            "name": "example"
          }
        ]
      }
    }
  }
}
...

🎨 Styling

As the generated docs are just plain HTML files you apply whatever styling you want. For convinience ngx-doc-gen comes with two SCSS mixins.

core

Applies some general styles for font, spacing, borders, etc. Just include the mixing in your root stylesheet.

@use 'ngx-doc-gen/styles' as ngx-doc-gen;

@include ngx-doc-gen.core();

docs-theme

Applies some Angular Material touch. Just pass your Angular Material theme into the mixin.

@use 'ngx-doc-gen/styles/theming' as ngx-doc-gen;

@include ngx-doc-gen.docs-theme($theme);