Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bohoffi/ngx-doc-gen
Angular library documentation generator utilizing dgeni
https://github.com/bohoffi/ngx-doc-gen
angular angular-cli cli dgeni documentation-generator documentations generator nx nx-plugin
Last synced: about 2 months ago
JSON representation
Angular library documentation generator utilizing dgeni
- Host: GitHub
- URL: https://github.com/bohoffi/ngx-doc-gen
- Owner: bohoffi
- License: apache-2.0
- Archived: true
- Created: 2022-02-19T20:29:00.000Z (over 2 years ago)
- Default Branch: develop
- Last Pushed: 2024-02-27T18:31:56.000Z (9 months ago)
- Last Synced: 2024-09-24T10:03:47.646Z (about 2 months ago)
- Topics: angular, angular-cli, cli, dgeni, documentation-generator, documentations, generator, nx, nx-plugin
- Language: TypeScript
- Homepage: https://bohoffi.github.io/ngx-doc-gen/
- Size: 2.17 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
> [!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.
[npm-image]: https://badge.fury.io/js/ngx-doc-gen.svg
[npm-url]: https://www.npmjs.com/package/ngx-doc-gen
# ngx-doc-gen 📚 [](https://www.npmjs.com/package/ngx-doc-gen)
> 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](https://github.com/angular/components)) who are using a perfectly working base implementation on documentation generation utilizing [Dgeni](https://github.com/angular/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:
```bash
npm install --save-dev ngx-doc gen
nx generate ngx-doc-gen:configure
```
Using Angular CLI
```bash
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:
```bash
nx run :doc-gen
```
Using Angular CLI:
```bash
ng doc-gen
```
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. |
```json
// Example given for a project.json
...
"": {
"targets": {
"doc-gen": {
"executor": "ngx-doc-gen:generate",
"options": {
"logLevel": "verbose",
"outputPath": "./docs/libs/",
"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.
```scss
@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.
```scss
@use 'ngx-doc-gen/styles/theming' as ngx-doc-gen;
@include ngx-doc-gen.docs-theme($theme);
```