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
- Generator
- Executor
- Recipes
- Workspace Docs
- Watch Mode
- Integration with @nx/storybook

Getting Started

Add the plugin to your Nx workspace:

``
npm install --save-dev @twittwer/compodoc
`

Configure Compodoc for a project:

`shell script
nx g @twittwer/compodoc:config


adds a compodoc target to the specified project




ensures @compodoc/compodoc as devDependencies


`

Run nx run :compodoc --serve and go to http://localhost:8080/

Generator

Add Compodoc target to a project:

`
nx g @twittwer/compodoc:config [options]
`

| Option | Default | Description |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| workspaceDocs | false | Will add a "tsconfig.compodoc.json" to the project that includes the whole workspace. Workspace Docs Recipe |

Executor

Generate Compodoc documentation for a project:

`shell script


HTML Format

nx run :compodoc

JSON Format

nx run :compodoc:json
`

The 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 | /tsconfig.json | Path to project's tsconfig file. |
| outputPath | dist/compodoc/ | 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 | | 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

How to configure an executor?

The target definition can be found in angular.json/workspace.json in the workspace root or project.json in the project directory:


`json5
{
"targets": {
"compodoc": {
"executor": "@twittwer/compodoc:compodoc",
"options": { / Define your common options here / },
"configurations": {
"": { / and provide use case specific options via configurations. / }
}
}
}
}
`


Recipes

$3

> 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

$3

> Rebuild your documentation on file changes during development.

The watch mode can be activated via argument:

`shell script
nx run :compodoc --watch # watch mode automatically enables serving
nx run :compodoc:json --watch
`

or via explicit configuration:


`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 }
}
}
}
}
`


$3

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:




Option 1: storybook / storybook:build (1 target with configuration)


`json5
{
"targets": {
"_storybook": { / @nx/storybook / },
"_build-storybook": { / @nx/storybook / },
"compodoc": { / @twittwer/compodoc / },
"storybook": {
"executor": "@nx/workspace:run-commands",
"options": {
"commands": [
"npx nx run :compodoc:json --watch",
"npx nx run :_storybook"
],
"parallel": true
},
"configurations": {
"build": {
"commands": [
"npx nx run :compodoc:json",
"npx nx run :_build-storybook"
],
"parallel": false
}
}
}
}
}
`





Option 2: storybook / build-storybook (2 targets)


`json5
{
"targets": {
"_storybook": { / @nx/storybook / },
"_build-storybook": { / @nx/storybook / },
"compodoc": { / @twittwer/compodoc / },
"storybook": {
"executor": "@nx/workspace:run-commands",
"options": {
"commands": [
"npx nx run :compodoc:json --watch",
"npx nx run :_storybook"
],
"parallel": true
}
},
"build-storybook": {
"executor": "@nx/workspace:run-commands",
"options": {
"commands": [
"npx nx run :compodoc:json",
"npx nx run :_build-storybook"
],
"parallel": false
}
}
}
}
`


Configure Storybook Docs in libs//.storybook/preview.js:

`js
import { setCompodocJson } from '@storybook/addon-docs/angular';
import compodocJson from '../../../dist/compodoc//documentation.json';

setCompodocJson(compodocJson);
`

Serve or build it:

`shell script


Option 1

nx run :storybook
nx run :storybook:build

Option 2

nx run :storybook
nx run :build-storybook
``