@twittwer/compodoc v1.12.0

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 @nrwl/storybook

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]

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

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:

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 @nrwl/storybook

At first you have to configure @nrwl/storybook & @twittwer/compodoc for the project.
Wrap storybook & build-storybook targets with a @nx/workspace:run-commands executor:

{
  "targets": {
    "_storybook": { /* @nrwl/storybook */ },
    "_build-storybook": {  /* @nrwl/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": { /* @nrwl/storybook */ },
    "_build-storybook": {  /* @nrwl/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