feat(core): add docs generation

docs/generated/cli/create-nx-workspace.md

@@ -0,0 +1,72 @@
+---
+title: 'create-nx-workspace - CLI command'
+description: 'Create a new Nx workspace'
+---
+
+# create-nx-workspace
+
+Create a new Nx workspace
+
+## Usage
+
+```bash
+create-nx-workspace [name] [options]
+```
+
+Install `create-nx-workspace` globally to invoke the command directly, or use `npx create-nx-workspace`, `yarn create nx-workspace`, or `pnpx create-nx-workspace`.
+
+## Options
+
+### allPrompts
+
+Show all prompts
+
+### appName
+
+The name of the application when a preset with pregenerated app is selected
+
+### cli
+
+CLI to power the Nx workspace
+
+### defaultBase
+
+Default: `main`
+
+Default base to use for new projects
+
+### help
+
+Show help
+
+### interactive
+
+Enable interactive mode with presets
+
+### name
+
+Workspace name (e.g. org name)
+
+### nxCloud
+
+Default: `true`
+
+Use Nx Cloud
+
+### packageManager
+
+Default: `npm`
+
+Package manager to use
+
+### preset
+
+Customizes the initial content of your workspace. To build your own see https://nx.dev/nx-plugin/overview#preset
+
+### style
+
+Style option to be used when a preset with pregenerated app is selected
+
+### version
+
+Show version number

docs/map.json

@@ -360,6 +360,11 @@
         "name": "CLI",
         "id": "cli",
         "itemList": [
+          {
+            "name": "create-nx-workspace",
+            "id": "create-nx-workspace",
+            "file": "generated/cli/create-nx-workspace"
+          },
           {
             "name": "generate",
             "id": "generate",

packages/create-nx-workspace/bin/create-nx-workspace.ts

@@ -27,7 +27,7 @@ type Arguments = {
   cli: string;
   style: string;
   nxCloud: boolean;
-  all: boolean;
+  allPrompts: boolean;
   packageManager: string;
   defaultBase: string;
 };
@@ -115,18 +115,17 @@ const cliVersion = 'NX_VERSION';
 const nxVersion = 'NX_VERSION';
 const prettierVersion = 'PRETTIER_VERSION';
 
-export const commandsObject: yargs.Argv<Arguments> = yargs(
-  process.argv.slice(2)
-)
+export const commandsObject: yargs.Argv<Arguments> = yargs
   .wrap(yargs.terminalWidth())
   .parserConfiguration({
     'strip-dashed': true,
     'dot-notation': false,
   })
   .strict()
   .command(
+    // this is the default and only command
     '$0 [name] [options]',
-    '✨ Create a new Nx workspace ✨',
+    'Create a new Nx workspace',
     (yargs) =>
       yargs
         .positional('name', {
@@ -161,7 +160,7 @@ export const commandsObject: yargs.Argv<Arguments> = yargs(
           defaultDescription: 'true',
           type: 'boolean',
         })
-        .option('all', {
+        .option('allPrompts', {
           alias: 'a',
           describe: `Show all prompts`,
           type: 'boolean',
@@ -190,11 +189,9 @@ export const commandsObject: yargs.Argv<Arguments> = yargs(
     },
     [getConfiguration]
   )
-  .help('help', 'Show this help')
+  .help('help')
   .version(nxVersion);
 
-commandsObject.argv;
-
 async function main(parsedArgs: yargs.Arguments<Arguments>) {
   const {
     name,
@@ -328,7 +325,7 @@ async function determinePackageManager(
     process.exit(1);
   }
 
-  if (parsedArgs.all) {
+  if (parsedArgs.allPrompts) {
     return enquirer
       .prompt([
         {
@@ -355,7 +352,7 @@ async function determineDefaultBase(
   if (parsedArgs.defaultBase) {
     return Promise.resolve(parsedArgs.defaultBase);
   }
-  if (parsedArgs.all) {
+  if (parsedArgs.allPrompts) {
     return enquirer
       .prompt([
         {

packages/create-nx-workspace/bin/index.ts

@@ -0,0 +1,3 @@
+import { commandsObject } from './create-nx-workspace';
+
+commandsObject.argv;

packages/create-nx-workspace/package.json

@@ -19,7 +19,7 @@
     "CLI"
   ],
   "bin": {
-    "create-nx-workspace": "./bin/create-nx-workspace.js"
+    "create-nx-workspace": "./bin/index.js"
   },
   "author": "Victor Savkin",
   "license": "MIT",
@@ -29,7 +29,7 @@
   "homepage": "https://nx.dev",
   "dependencies": {
     "tmp": "~0.2.1",
-    "yargs-parser": "20.0.0",
+    "yargs": "~15.4.1",
     "enquirer": "~2.3.6",
     "flat": "^5.0.2",
     "chalk": "4.1.0",

scripts/documentation/documentation.ts

@@ -1,6 +1,7 @@
 import * as chalk from 'chalk';
 import { execSync } from 'child_process';
 import { generateCLIDocumentation } from './generate-cli-data';
+import { generateCNWocumentation } from './generate-cnw-documentation';
 import { generateDevkitDocumentation } from './generate-devkit-documentation';
 import { generatePackageSchemas } from './package-schemas/generatePackageSchemas';
 
@@ -9,6 +10,7 @@ async function generate() {
     console.log(`${chalk.blue('i')} Generating Documentation`);
     generatePackageSchemas();
     generateDevkitDocumentation();
+    await generateCNWocumentation();
     await generateCLIDocumentation();
 
     console.log(`\n${chalk.green('✓')} Generated Documentation\n`);

scripts/documentation/generate-cnw-documentation.ts

@@ -0,0 +1,121 @@
+import * as chalk from 'chalk';
+import { join } from 'path';
+import { dedent } from 'tslint/lib/utils';
+import {
+  formatDeprecated,
+  sortAlphabeticallyFunction,
+  generateMarkdownFile,
+} from './utils';
+const importFresh = require('import-fresh');
+
+export async function generateCNWocumentation() {
+  process.env.NX_GENERATE_DOCS_PROCESS = 'true';
+
+  console.log(
+    `\n${chalk.blue(
+      'i'
+    )} Generating Documentation for Create Nx Workspace Command`
+  );
+
+  const { commandsObject } = importFresh(
+    '../../packages/create-nx-workspace/bin/create-nx-workspace'
+  );
+
+  const commandsOutputDirectory = join(
+    __dirname,
+    '../../docs/',
+    'generated',
+    'cli'
+  );
+
+  const command = commandsObject.getCommandInstance().getCommandHandlers()[
+    '$0'
+  ];
+  const parsedCommand = await parseCommand(command);
+  const markdown = generateMarkdown(parsedCommand);
+  generateMarkdownFile(commandsOutputDirectory, markdown);
+
+  delete process.env.NX_GENERATE_DOCS_PROCESS;
+
+  console.log(
+    `${chalk.green(
+      '✓'
+    )} Generated Documentation for Create Nx Workspace Command`
+  );
+}
+
+interface ParsedCommandOption {
+  name: string;
+  description: string;
+  default: string;
+  deprecated: boolean | string;
+}
+
+interface ParsedCommand {
+  commandString: string;
+  description: string;
+  options?: Array<ParsedCommandOption>;
+}
+
+async function parseCommand(command: any): Promise<ParsedCommand> {
+  const builder = await command.builder(importFresh('yargs')().resetOptions());
+  const builderDescriptions = builder.getUsageInstance().getDescriptions();
+  const builderDefaultOptions = builder.getOptions().default;
+  const builderAutomatedOptions = builder.getOptions().defaultDescription;
+  const builderDeprecatedOptions = builder.getDeprecatedOptions();
+
+  return {
+    description: command.description,
+    commandString: command.original.replace('$0', 'create-nx-workspace'),
+    options:
+      Object.keys(builderDescriptions).map((key) => ({
+        name: key,
+        description: builderDescriptions[key]
+          ? builderDescriptions[key].replace('__yargsString__:', '')
+          : '',
+        default: builderDefaultOptions[key] || builderAutomatedOptions[key],
+        deprecated: builderDeprecatedOptions[key],
+      })) || null,
+  };
+}
+
+function generateMarkdown(command: ParsedCommand) {
+  let template = dedent`
+  ---
+  title: "create-nx-workspace - CLI command"
+  description: "${command.description}"
+  ---
+  # create-nx-workspace
+
+  ${command.description}
+
+  ## Usage
+
+  \`\`\`bash
+  ${command.commandString}
+  \`\`\`
+
+  Install \`create-nx-workspace\` globally to invoke the command directly, or use \`npx create-nx-workspace\`, \`yarn create nx-workspace\`, or \`pnpx create-nx-workspace\`.\n`;
+
+  template += '\n## Options';
+  command.options
+    .sort((a, b) => sortAlphabeticallyFunction(a.name, b.name))
+    .forEach((option) => {
+      template += dedent`
+          ### ${option.deprecated ? `~~${option.name}~~` : option.name}
+          ${
+            option.default === undefined || option.default === ''
+              ? ''
+              : `Default: \`${option.default}\`\n`
+          }
+        `;
+      template += dedent`
+          ${formatDeprecated(option.description, option.deprecated)}
+        `;
+    });
+
+  return {
+    name: 'create-nx-workspace',
+    template,
+  };
+}