Warning
v2.4.0 is the last version as I do not have the time to maintain this lib any longer. If anyone might want to take the maintenance please feel free to reach out to me.
Automatically generate your library's API docs using Angular CLI or NX.
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.
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.
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).
- 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
- NX:
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.
- Type:
'error' | 'warn' | 'debug' | 'verbose'
- Defines the log level Dgeni uses while generation
- Default:
'warn'
- Type:
Path
- Defines the output path for the generated files (relative to working directory)
- Default:
'docs'
- Type:
string[]
- Defines base clases to exclude from generation
- Default:
[]
- Example:
- Your API contains a service extending
Observable
which would include members likesubscribe()
in your documentation. This could be prevented as follows: --exclude-base Observable
- Your API contains a service extending
- Type:
string
- Tag to enforce documentation of usually private symbols. Only applies to symbols at least exported.
- Default:
docs-public
- Type:
string
, - Tag to explicitly hide symbols from documentation.
- Default:
docs-private
- Type:
string
, - Tag indicating the version with which a deprecated symbol will get removed.
- Default:
breaking-change
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.
- 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"
}
]
}
}
}
}
...
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.
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();
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);