No Painful Merges

    @twittwer/compodoc
    TypeScript icon, indicating that this package has built-in type declarations

    1.9.0 • Public • Published

    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.
    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 @nrwl/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 @nrwl/workspace:run-commands executor:

    Option 1: `storybook` / `storybook:build` (1 target with configuration)
    {
      "targets": {
        "_storybook": { /* @nrwl/storybook */ },
        "_build-storybook": {  /* @nrwl/storybook */ },
        "compodoc": { /* @twittwer/compodoc */ },
        "storybook": {
          "executor": "@nrwl/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": { /* @nrwl/storybook */ },
        "_build-storybook": {  /* @nrwl/storybook */ },
        "compodoc": { /* @twittwer/compodoc */ },
        "storybook": {
          "executor": "@nrwl/workspace:run-commands",
          "options": {
            "commands": [
              "npx nx run <project>:compodoc:json --watch",
              "npx nx run <project>:_storybook"
            ],
            "parallel": true
          }
        },
        "build-storybook": {
          "executor": "@nrwl/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

    Install

    npm i @twittwer/compodoc

    DownloadsWeekly Downloads

    6,661

    Version

    1.9.0

    License

    MIT

    Unpacked Size

    65.8 kB

    Total Files

    19

    Last publish

    Collaborators

    • twittwer