chore(repo): docs generation should work on windows (#27444)

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior
<!-- This is the behavior we have today -->

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #

scripts/documentation/generators/generate-devkit-documentation.ts

@@ -1,9 +1,10 @@
 import * as chalk from 'chalk';
+import * as typedoc from 'typedoc';
 import { execSync, ExecSyncOptions } from 'child_process';
-import { readFileSync, writeFileSync } from 'fs';
+import { cpSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
-export function generateDevkitDocumentation() {
+export async function generateDevkitDocumentation() {
   console.log(`\n${chalk.blue('i')} Generating Documentation for Devkit\n`);
 
   const execSyncOptions: ExecSyncOptions = {
@@ -11,14 +12,18 @@ export function generateDevkitDocumentation() {
     // stdio: process.env.CI === 'true' ? 'inherit' : 'ignore',
   };
 
-  execSync(
+  execSync('nx run-many -t build -p devkit,typedoc-theme', execSyncOptions);
-    'nx build devkit && nx build typedoc-theme && rm -rf node_modules/@nx/typedoc-theme && cp -R dist/typedoc-theme node_modules/@nx/typedoc-theme',
-    execSyncOptions
-  );
 
-  execSync(
+  rmSync('node_modules/@nx/typedoc-theme', { recursive: true, force: true });
-    'cp packages/devkit/tsconfig.lib.json build/packages/devkit/tsconfig.lib.json',
+
-    execSyncOptions
+  cpSync('dist/typedoc-theme', 'node_modules/@nx/typedoc-theme', {
+    recursive: true,
+  });
+
+  cpSync(
+    'packages/devkit/tsconfig.lib.json',
+    'build/packages/devkit/tsconfig.lib.json',
+    { recursive: true }
   );
 
   writeFileSync(
@@ -31,16 +36,42 @@ export function generateDevkitDocumentation() {
       )
   );
 
-  execSync(
+  rmSync('docs/generated/devkit', { recursive: true, force: true });
-    `rm -rf docs/generated/devkit && pnpm typedoc build/packages/devkit/index.d.ts --tsconfig build/packages/devkit/tsconfig.lib.json --out ./docs/generated/devkit --plugin typedoc-plugin-markdown --plugin @nx/typedoc-theme --hideBreadcrumbs true --disableSources --allReflectionsHaveOwnDocument --publicPath ../../devkit/ --theme nx-markdown-theme --excludePrivate --readme none`,
+
-    execSyncOptions
+  const commonTypedocOptions: Partial<typedoc.TypeDocOptions> & {
-  );
+    [key: string]: unknown;
-  execSync(
+  } = {
-    `pnpm typedoc build/packages/devkit/ngcli-adapter.d.ts --tsconfig build/packages/devkit/tsconfig.lib.json --out ./docs/generated/devkit/ngcli_adapter --plugin typedoc-plugin-markdown --plugin @nx/typedoc-theme --hideBreadcrumbs true --disableSources --allReflectionsHaveOwnDocument --publicPath ../../devkit/ngcli_adapter/ --theme nx-markdown-theme --readme none`,
+    plugin: ['typedoc-plugin-markdown', '@nx/typedoc-theme'],
-    execSyncOptions
+    disableSources: true,
-  );
+    theme: 'nx-markdown-theme',
-  execSync(`rm -rf build/packages/devkit/tsconfig.lib.json`, execSyncOptions);
+    readme: 'none',
-  execSync(`rm -rf docs/generated/devkit/.nojekyll`, execSyncOptions);
+    hideBreadcrumbs: true,
+    allReflectionsHaveOwnDocument: true,
+  } as const;
+
+  await runTypedoc({
+    ...commonTypedocOptions,
+    entryPoints: ['build/packages/devkit/index.d.ts'],
+    tsconfig: 'build/packages/devkit/tsconfig.lib.json',
+    out: 'docs/generated/devkit',
+    excludePrivate: true,
+    publicPath: '../../devkit/',
+  });
+
+  await runTypedoc({
+    ...commonTypedocOptions,
+    entryPoints: ['build/packages/devkit/ngcli-adapter.d.ts'],
+    tsconfig: 'build/packages/devkit/tsconfig.lib.json',
+    out: 'docs/generated/devkit/ngcli_adapter',
+    publicPath: '../../devkit/ngcli_adapter/',
+  });
+
+  rmSync('build/packages/devkit/tsconfig.lib.json', {
+    recursive: true,
+    force: true,
+  });
+  rmSync('docs/generated/devkit/.nojekyll', { recursive: true, force: true });
+
   execSync(
     `pnpm prettier docs/generated/devkit --write --config ${join(
       __dirname,
@@ -52,3 +83,21 @@ export function generateDevkitDocumentation() {
     execSyncOptions
   );
 }
+
+async function runTypedoc(
+  options: Partial<typedoc.TypeDocOptions> & { [key: string]: unknown }
+) {
+  const app = await typedoc.Application.bootstrapWithPlugins(
+    options as Partial<typedoc.TypeDocOptions>,
+    [
+      new typedoc.TypeDocReader(),
+      new typedoc.PackageJsonReader(),
+      new typedoc.TSConfigReader(),
+    ]
+  );
+  const project = await app.convert();
+  if (!project) {
+    throw new Error('Failed to convert the project');
+  }
+  await app.generateDocs(project, app.options.getValue('out'));
+}

scripts/documentation/generators/main.ts

@@ -25,7 +25,7 @@ async function generate() {
     await generateCnwDocumentation(commandsOutputDirectory);
     await generateCliDocumentation(commandsOutputDirectory);
 
-    generateDevkitDocumentation();
+    await generateDevkitDocumentation();
     await generatePackageSchemas();
 
     await generateManifests(workspaceRoot);