twittwer
Compodoc (Nx Plugin)
Nx Plugin to generate documentation via Compodoc.
NOTE: The whole generation part is done by @compodoc/compodoc, this is just a wrapper plugin for Nx workspaces.
Getting Started
Add the plugin to your Nx workspace:
npm install --save-dev @twittwer/compodocConfigure Compodoc for a project:
`shell script
nx g @twittwer/compodoc:config <project>
adds a compodoc target to the specified project
ensures @compodoc/compodoc as devDependencies
Run `nx run <project>:compodoc --serve` and go to [http://localhost:8080/](http://localhost:8080/)
## Generator
Add Compodoc target to a project:
nx g @twittwer/compodoc:config <project> [options]
| Option | Default | Description |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| workspaceDocs | `false` | Will add a "tsconfig.compodoc.json" to the project that includes the whole workspace. [Workspace Docs Recipe](#workspace-docs) |
## Executor
Generate Compodoc documentation for a project:
```shell script
# HTML Format
nx run <project>:compodoc
# JSON Format
nx run <project>:compodoc:jsonThe executor supports several configuration options that are passed to the Compodoc command.
Additional options (used exclusively by the executor) are indicated by an italic written option name.
For more details you may have a look at the original Compodoc documentation or the builder's schema.json
| Option | Default | Description |
|---|---|---|
| tsConfig | <projectRoot>/tsconfig.json |
Path to project's tsconfig file. |
| outputPath | dist/compodoc/<projectName> |
The output path of the generated files. |
| exportFormat | html |
Format of generated documentation. (html, json - enables Compodoc's minimal mode as well) |
| workspaceDocs | false |
Use readme of workspace root as entry and add the readme files of all project as additional documentation. |
| | | ||
| name | <projectName> |
Title of the documentation. (workspaceDocs uses workspace name as default - defined in package.json) |
| | | ||
| includes | | Path to external markdown files, folder should contain a summary.json. (workspaceDocs will override this) |
|
| includesName | | Name of menu item containing external markdown files. (workspaceDocs uses "Projects" as default) |
|
| | | ||
| assetsFolder | | External assets folder to copy in generated documentation folder. | |
| unitTestCoverage | | Path to unit test coverage in json-summary format. | |
| | | ||
| disableCoverage | true |
Do not add the documentation coverage report. |
| disableSourceCode | false |
Do not add source code tab and links to source code. |
| disableDomTree | false |
Do not add dom tree tab. |
| disableTemplateTab | false |
Do not add template tab. |
| disableStyleTab | false |
Do not add style tab. |
| disableGraph | false |
Disable rendering of the dependency graph. |
| disablePrivate | true |
Do not show private in generated documentation. |
| disableProtected | false |
Do not show protected in generated documentation. |
| disableInternal | true |
Do not show @internal in generated documentation. |
| disableLifeCycleHooks | true |
Do not show Angular lifecycle hooks in generated documentation. |
| disableRoutesGraph | false |
Do not add the routes graph. |
| disableSearch | false |
Do not add the search input. |
| disableDependencies | false |
Do not add the dependencies list. |
| | | ||
| coverageTest | 0 |
Threshold for global documentation coverage. |
| coverageMinimumPerFile | 0 |
Threshold for documentation coverage of each file. |
| coverageTestThresholdFail | true |
Abort compodoc with an error instead of a warn log, if coverage threshold (global or per file) is not reached (true: error, false: warn). |
| | | ||
| language | en-US |
Language used for generated documentation. |
| theme | gitbook |
Theme used for generated documentation. |
| extTheme | | Path to external theme file. | |
| templates | | Path to directory of Handlebars templates to override built-in templates. | |
| customLogo | | Path to custom logo. | |
| customFavicon | | Path to custom favicon. | |
| hideGenerator | false |
Do not print the Compodoc logo at the bottom of the page. |
| | | ||
| serve | false (true in watch mode) |
Serve generated documentation. (automatically enabled in watch mode) |
| port | 8080 |
Port for serving of documentation. |
| watch | false |
Watch for source files changes to automatically rebuild documentation. |
| silent | true (false in watch/serve mode) |
Suppress verbose build output. |
| | | ||
| debug | false |
Log resulting executor options & the final Compodoc command with all arguments. |
All paths should be relative to workspace root
The target definition can be found in angular.json/workspace.json in the workspace root or project.json in the project directory:
{
"targets": {
"compodoc": {
"executor": "@twittwer/compodoc:compodoc",
"options": { /* Define your common options here */ },
"configurations": {
"<configuration name>": { /* and provide use case specific options via configurations. */ }
}
}
}
}Recipes
Workspace Docs
Documentation for the whole workspace incl. the README files of all projects (apps/libs) as additional documentation.
- Create a library for shared/workspace wide tooling (e.g.
workspace)nx g @nx/workspace:library workspace --unitTestRunner=none - Optionally you can delete some unused code (you should keep at least
tsconfig.json&README.md). - Configure Compodoc for the created project
nx g @twittwer/compodoc:config workspace --workspaceDocs - Generate your docs:
nx run workspace:compodoc
Watch Mode
Rebuild your documentation on file changes during development.
The watch mode can be activated via argument:
`shell script
nx run <project>:compodoc --watch # watch mode automatically enables serving
nx run <project>:compodoc:json --watch
or via explicit configuration:
<!-- prettier-ignore-start -->
```json5
{
"targets": {
"compodoc": {
"executor": "@twittwer/compodoc:compodoc",
"options": { /* Define your common options here */ },
"configurations": {
"serve": { "watch": true }, /* watch mode automatically enables serving */
"json": { "exportFormat": "json" },
"json.watch": { "exportFormat": "json", "watch": true }
}
}
}
}Integration with @nx/storybook
At first you have to configure @nx/storybook & @twittwer/compodoc for the project.
Wrap storybook & build-storybook targets with a @nx/workspace:run-commands executor:
{
"targets": {
"_storybook": { /* @nx/storybook */ },
"_build-storybook": { /* @nx/storybook */ },
"compodoc": { /* @twittwer/compodoc */ },
"storybook": {
"executor": "@nx/workspace:run-commands",
"options": {
"commands": [
"npx nx run <project>:compodoc:json --watch",
"npx nx run <project>:_storybook"
],
"parallel": true
},
"configurations": {
"build": {
"commands": [
"npx nx run <project>:compodoc:json",
"npx nx run <project>:_build-storybook"
],
"parallel": false
}
}
}
}
}{
"targets": {
"_storybook": { /* @nx/storybook */ },
"_build-storybook": { /* @nx/storybook */ },
"compodoc": { /* @twittwer/compodoc */ },
"storybook": {
"executor": "@nx/workspace:run-commands",
"options": {
"commands": [
"npx nx run <project>:compodoc:json --watch",
"npx nx run <project>:_storybook"
],
"parallel": true
}
},
"build-storybook": {
"executor": "@nx/workspace:run-commands",
"options": {
"commands": [
"npx nx run <project>:compodoc:json",
"npx nx run <project>:_build-storybook"
],
"parallel": false
}
}
}
}Configure Storybook Docs in libs/<project>/.storybook/preview.js:
import { setCompodocJson } from '@storybook/addon-docs/angular';
import compodocJson from '../../../dist/compodoc/<project>/documentation.json';
setCompodocJson(compodocJson);Serve or build it:
`shell script
Option 1
nx run <project>:storybook nx run <project>:storybook:build
Option 2
nx run <project>:storybook
nx run <project>:build-storybook
`