Skip to content

Latest commit

 

History

History

compodoc

README.md

Compodoc (Nx Plugin)

npm version commitizen friendly styled with prettier

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/compodoc

Configure Compodoc for a project:

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/

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

Executor

Generate Compodoc documentation for a project:

# HTML Format
nx run <project>:compodoc
# JSON Format
nx run <project>: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 <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

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:

{
  "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:

nx run <project>:compodoc --watch # watch mode automatically enables serving
nx run <project>:compodoc:json --watch

or via explicit configuration:

{
  "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:

Option 1: `storybook` / `storybook:build` (1 target with configuration) 
{
  "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
        }
      }
    }
  }
}
Option 2: `storybook` / `build-storybook` (2 targets) 
{
  "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:

# Option 1
nx run <project>:storybook
nx run <project>:storybook:build
# Option 2
nx run <project>:storybook
nx run <project>:build-storybook