feat(compodoc): add watch mode (#21)

Adding watch mode with nodemon workaround for JSON format (compodoc/compodoc#862)

libs/compodoc/README.md

@@ -15,6 +15,7 @@
 - [Builder](#builder)
 - [Recipes](#recipes)
   - [Workspace Docs](#workspace-docs)
+  - [Watch Mode](#watch-mode)
 
 ## Installation
 
@@ -34,7 +35,7 @@ ng g @twittwer/compodoc:config <project>
 
 ## Schematics
 
-Add compodoc target to a project:
+Add Compodoc target to a project:
 
 ```
 ng g @twittwer/compodoc:config <project> [options]
@@ -139,7 +140,7 @@ Additional options (used by the builder only) are indicated by an italic written
 
 ### Workspace Docs
 
-This recipe will describe how to create a Compodoc documentation including your whole workspace and listing the Readme files of all projects.
+> Compodoc of the whole workspace incl. all project READMEs (apps/libs) as additional documentation.
 
 1. Create a library for shared/workspace wide tooling (e.g. `tools`)  
    `ng g @nrwl/(workspace|angular):library <project> [--unitTestRunner=none]`  
@@ -151,3 +152,34 @@ This recipe will describe how to create a Compodoc documentation including your
 4. Generate your docs:  
    `ng run <project>:compodoc`  
    `ng run tools:compodoc`
+
+### Watch Mode
+
+> Rebuild your documentation on file changes during development.
+
+The watch mode can be activated via argument:
+
+```shell script
+ng run <project>:compodoc --watch
+ng run <project>:compodoc:json --watch
+```
+
+or via additional connfiguration:
+
+```json5
+configurations: {
+  "json": {
+    "exportFormat": "json"
+  },
+  "watch": {
+    "watch": true
+  },
+  "json-watch": {
+    "exportFormat": "json",
+    "watch": true
+  }
+}
+```
+
+> Compodoc doesn't support watch mode while using JSON as export format ([#862](https://github.com/compodoc/compodoc/issues/862)).
+> This scenario is handled by the use of [nodemon](https://github.com/remy/nodemon) to watch source files and rerun Compodoc on changes.

libs/compodoc/package.json

@@ -24,6 +24,9 @@
   "main": "src/index.js",
   "schematics": "./collection.json",
   "builders": "./builders.json",
+  "dependencies": {
+    "nodemon": "^2.0.6"
+  },
   "peerDependencies": {
     "@nrwl/workspace": "*",
     "@compodoc/compodoc": "^1.1.11"

libs/compodoc/src/builders/compodoc/builder.ts

@@ -4,13 +4,8 @@ import {
   createBuilder,
 } from '@angular-devkit/architect';
 import { CompodocBuilderSchema } from './schema';
-import { ChildProcess, spawn } from 'child_process';
 import { resolve } from 'path';
-import {
-  buildCompodocArgs,
-  buildCompodocCmd,
-  createEmptyCompodocJson,
-} from './compodoc-utils';
+import { spawnCompodocProcess } from './compodoc-utils';
 import { ProjectType } from '@nrwl/workspace';
 
 async function runBuilder(
@@ -35,25 +30,10 @@ async function runBuilder(
     options.outputPath ?? resolve('dist', 'compodoc', project);
 
   return new Promise<BuilderOutput>(res => {
-    const command = buildCompodocCmd(options, context);
-    const args = buildCompodocArgs(options, { ...context, projectRoot });
-
-    let childProcess: ChildProcess;
-    if (options.watch && options.exportFormat === 'json') {
-      createEmptyCompodocJson(workspaceRoot, options);
-
-      const compodocCommand = `${command} ${args.join(' ')}`;
-      const nodemonCommand = `npx nodemon --ignore dist --ext ts --exec "${compodocCommand}"`;
-      childProcess = spawn(nodemonCommand, [], {
-        cwd: options.workspaceDocs ? workspaceRoot : projectRoot,
-        shell: true,
-      });
-    } else {
-      childProcess = spawn(command, args, {
-        cwd: options.workspaceDocs ? workspaceRoot : projectRoot,
-        shell: true,
-      });
-    }
+    const childProcess = spawnCompodocProcess(options, {
+      ...context,
+      projectRoot,
+    });
 
     process.on('exit', () => childProcess.kill());
 

libs/compodoc/src/builders/compodoc/compodoc-utils.ts

@@ -11,16 +11,25 @@ import {
   mkdtempSync,
   writeFileSync,
 } from 'fs';
+import { ChildProcess, spawn } from 'child_process';
 
-export function buildCompodocCmd(
+function buildCompodocCmd(
   options: CompodocBuilderSchema,
   context: BuilderContext,
-) {
+): string {
   const { workspaceRoot } = context;
   return resolve(workspaceRoot, 'node_modules', '.bin', 'compodoc');
 }
 
-function buildIncludesFolderForWorkspace(
+function buildNodemonCmd(
+  options: CompodocBuilderSchema,
+  context: BuilderContext,
+): string {
+  const { workspaceRoot } = context;
+  return resolve(workspaceRoot, 'node_modules', '.bin', 'nodemon');
+}
+
+function createIncludesFolderForWorkspace(
   options: CompodocBuilderSchema,
   context: BuilderContext,
 ): string {
@@ -113,7 +122,7 @@ function getRelativePath(
   return relative(workspaceDocs ? workspaceRoot : projectRoot, absolutePath);
 }
 
-export function buildCompodocArgs(
+function buildCompodocArgs(
   options: CompodocBuilderSchema,
   context: BuilderContext & { projectRoot: string },
 ): string[] {
@@ -146,7 +155,7 @@ export function buildCompodocArgs(
   }
 
   if (options.workspaceDocs) {
-    const includesPath = buildIncludesFolderForWorkspace(options, context);
+    const includesPath = createIncludesFolderForWorkspace(options, context);
     args.push(`--includes=${includesPath}`);
     args.push(`--includesName=${options.includesName ?? 'Projects'}`);
   } else {
@@ -236,9 +245,9 @@ export function buildCompodocArgs(
   return args;
 }
 
-export function createEmptyCompodocJson(
-  workspaceRoot: string,
+function createEmptyCompodocJson(
   options: CompodocBuilderSchema,
+  { workspaceRoot }: BuilderContext,
 ) {
   mkdirSync(resolve(workspaceRoot, options.outputPath), {
     recursive: true,
@@ -266,3 +275,30 @@ export function createEmptyCompodocJson(
     }),
   );
 }
+
+export function spawnCompodocProcess(
+  options: CompodocBuilderSchema,
+  context: BuilderContext & { projectRoot: string },
+): ChildProcess {
+  const processOptions = {
+    cwd: options.workspaceDocs ? context.workspaceRoot : context.projectRoot,
+    shell: true,
+  };
+
+  const compodocCmd = buildCompodocCmd(options, context);
+  const compodocArgs = buildCompodocArgs(options, context);
+
+  if (options.watch && options.exportFormat === 'json') {
+    createEmptyCompodocJson(options, context);
+
+    const nodemonCmd = buildNodemonCmd(options, context);
+    const nodemonArgs = [
+      '--ignore dist',
+      '--ext ts',
+      `--exec "${compodocCmd} ${compodocArgs.join(' ')}"`,
+    ];
+    return spawn(nodemonCmd, nodemonArgs, processOptions);
+  }
+
+  return spawn(compodocCmd, compodocArgs, processOptions);
+}