From 15d8222200d23cef0c33fa4089f651b86b290a69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Jona=C5=A1?= Date: Thu, 31 Mar 2022 10:15:49 +0200 Subject: [PATCH] feat(nxdev): add types to CLI docs (#9607) --- docs/generated/cli/affected-apps.md | 32 +++++++++++++-- docs/generated/cli/affected-graph.md | 50 ++++++++++++++++++++--- docs/generated/cli/affected-libs.md | 32 +++++++++++++-- docs/generated/cli/affected.md | 36 ++++++++++++++-- docs/generated/cli/connect-to-nx-cloud.md | 4 ++ docs/generated/cli/create-nx-workspace.md | 38 +++++++++++++---- docs/generated/cli/daemon.md | 8 +++- docs/generated/cli/format-check.md | 36 ++++++++++++++-- docs/generated/cli/format-write.md | 36 ++++++++++++++-- docs/generated/cli/graph.md | 24 ++++++++++- docs/generated/cli/list.md | 6 +++ docs/generated/cli/migrate.md | 12 ++++++ docs/generated/cli/print-affected.md | 34 +++++++++++++-- docs/generated/cli/run-many.md | 32 +++++++++++++-- docs/generated/cli/workspace-generator.md | 8 ++++ scripts/documentation/utils.ts | 45 ++++++++++++-------- 16 files changed, 378 insertions(+), 55 deletions(-) diff --git a/docs/generated/cli/affected-apps.md b/docs/generated/cli/affected-apps.md index 2849cdc215eff..44d268dd1fc8f 100644 --- a/docs/generated/cli/affected-apps.md +++ b/docs/generated/cli/affected-apps.md @@ -39,37 +39,53 @@ nx affected:apps --base=main~1 --head=main ### all +Type: boolean + All projects ### base +Type: string + Base of the current branch (usually main) ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### files +Type: array + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +Type: string + Latest commit of the current branch (usually HEAD) ### help +Type: boolean + Show help ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -81,20 +97,28 @@ Produces a plain output for affected:apps and affected:libs ### runner +Type: string + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +Type: boolean + Uncommitted changes ### untracked +Type: boolean + Untracked changes ### verbose @@ -103,4 +127,6 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/affected-graph.md b/docs/generated/cli/affected-graph.md index ba409666b2fad..c86e74514defb 100644 --- a/docs/generated/cli/affected-graph.md +++ b/docs/generated/cli/affected-graph.md @@ -57,53 +57,77 @@ nx affected:graph --exclude=project-one,project-two ### all +Type: boolean + All projects ### base +Type: string + Base of the current branch (usually main) ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### file +Type: string + Output file (e.g. --file=output.json or --file=dep-graph.html) ### files +Type: array + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### focus +Type: string + Use to show the project graph for a particular project and every node that is either an ancestor or a descendant. ### groupByFolder +Type: boolean + Group projects by folder in the project graph ### head +Type: string + Latest commit of the current branch (usually HEAD) ### help +Type: boolean + Show help ### host +Type: string + Bind the project graph server to a specific ip address. ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -111,30 +135,42 @@ Isolate projects which previously failed ### open -Default: `true` +Type: boolean + +Default: true Open the project graph in the browser. ### port +Type: number + Bind the project graph server to a specific port. ### runner +Type: string + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +Type: boolean + Uncommitted changes ### untracked +Type: boolean + Untracked changes ### verbose @@ -143,10 +179,14 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number ### watch -Default: `false` +Type: boolean + +Default: false Watch for changes to project graph and update in-browser diff --git a/docs/generated/cli/affected-libs.md b/docs/generated/cli/affected-libs.md index 27bab31a502bd..fab38002afb72 100644 --- a/docs/generated/cli/affected-libs.md +++ b/docs/generated/cli/affected-libs.md @@ -39,37 +39,53 @@ nx affected:libs --base=main~1 --head=main ### all +Type: boolean + All projects ### base +Type: string + Base of the current branch (usually main) ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### files +Type: array + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +Type: string + Latest commit of the current branch (usually HEAD) ### help +Type: boolean + Show help ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -81,20 +97,28 @@ Produces a plain output for affected:apps and affected:libs ### runner +Type: string + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +Type: boolean + Uncommitted changes ### untracked +Type: boolean + Untracked changes ### verbose @@ -103,4 +127,6 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/affected.md b/docs/generated/cli/affected.md index 31c8b5d9515ea..91b7facb03a55 100644 --- a/docs/generated/cli/affected.md +++ b/docs/generated/cli/affected.md @@ -57,37 +57,53 @@ nx affected --target=test --base=main~1 --head=main ### all +Type: boolean + All projects ### base +Type: string + Base of the current branch (usually main) ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### files +Type: array + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +Type: string + Latest commit of the current branch (usually HEAD) ### help +Type: boolean + Show help ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -95,28 +111,40 @@ Isolate projects which previously failed ### parallel +Type: string + Max number of parallel processes [default is 3] ### runner +Type: string + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### target +Type: string + Task to run for affected projects ### uncommitted +Type: boolean + Uncommitted changes ### untracked +Type: boolean + Untracked changes ### verbose @@ -125,4 +153,6 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/connect-to-nx-cloud.md b/docs/generated/cli/connect-to-nx-cloud.md index bc65d4a7bb272..e2f1904114dba 100644 --- a/docs/generated/cli/connect-to-nx-cloud.md +++ b/docs/generated/cli/connect-to-nx-cloud.md @@ -19,8 +19,12 @@ nx connect-to-nx-cloud ### help +Type: boolean + Show help ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/create-nx-workspace.md b/docs/generated/cli/create-nx-workspace.md index 5f0fa095daeb5..3baaa35547b53 100644 --- a/docs/generated/cli/create-nx-workspace.md +++ b/docs/generated/cli/create-nx-workspace.md @@ -19,62 +19,86 @@ Install `create-nx-workspace` globally to invoke the command directly, or use `n ### allPrompts -Default: `false` +Type: boolean + +Default: false Show all prompts ### appName +Type: string + The name of the application when a preset with pregenerated app is selected ### cli -Choices: `["nx", "angular"]` +Type: string + +Choices: ["nx", "angular"] CLI to power the Nx workspace ### defaultBase -Default: `main` +Type: string + +Default: main Default base to use for new projects ### help +Type: boolean + Show help ### interactive +Type: boolean + Enable interactive mode with presets ### name +Type: string + Workspace name (e.g. org name) ### nxCloud -Default: `true` +Type: boolean + +Default: true Use Nx Cloud ### packageManager -Default: `npm` +Type: string + +Choices: ["npm", "pnpm", "yarn"] -Choices: `["npm", "pnpm", "yarn"]` +Default: npm Package manager to use ### preset -Choices: `["apps", "empty", "core", "npm", "ts", "web-components", "angular", "angular-nest", "react", "react-express", "react-native", "next", "nest", "express"]` +Type: string + +Choices: ["apps", "empty", "core", "npm", "ts", "web-components", "angular", "angular-nest", "react", "react-express", "react-native", "next", "nest", "express"] Customizes the initial content of your workspace. To build your own see https://nx.dev/nx-plugin/overview#preset ### style +Type: string + Style option to be used when a preset with pregenerated app is selected ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/daemon.md b/docs/generated/cli/daemon.md index 51de33da34ea4..056eddf3b5be5 100644 --- a/docs/generated/cli/daemon.md +++ b/docs/generated/cli/daemon.md @@ -19,12 +19,18 @@ nx daemon ### background -Default: `true` +Type: boolean + +Default: true ### help +Type: boolean + Show help ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/format-check.md b/docs/generated/cli/format-check.md index cf036cf7991e2..d8cc9b8e7ab7c 100644 --- a/docs/generated/cli/format-check.md +++ b/docs/generated/cli/format-check.md @@ -19,41 +19,59 @@ nx format:check ### all +Type: boolean + All projects ### base +Type: string + Base of the current branch (usually main) ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### files +Type: array + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +Type: string + Latest commit of the current branch (usually HEAD) ### help +Type: boolean + Show help ### libs-and-apps +Type: boolean + Format only libraries and applications files. ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -61,24 +79,34 @@ Isolate projects which previously failed ### projects +Type: array + Projects to format (comma delimited) ### runner +Type: string + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +Type: boolean + Uncommitted changes ### untracked +Type: boolean + Untracked changes ### verbose @@ -87,4 +115,6 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/format-write.md b/docs/generated/cli/format-write.md index 19bad53591dcd..d2676bbc71e9a 100644 --- a/docs/generated/cli/format-write.md +++ b/docs/generated/cli/format-write.md @@ -19,41 +19,59 @@ nx format:write ### all +Type: boolean + All projects ### base +Type: string + Base of the current branch (usually main) ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### files +Type: array + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +Type: string + Latest commit of the current branch (usually HEAD) ### help +Type: boolean + Show help ### libs-and-apps +Type: boolean + Format only libraries and applications files. ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -61,24 +79,34 @@ Isolate projects which previously failed ### projects +Type: array + Projects to format (comma delimited) ### runner +Type: string + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +Type: boolean + Uncommitted changes ### untracked +Type: boolean + Untracked changes ### verbose @@ -87,4 +115,6 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/graph.md b/docs/generated/cli/graph.md index 9c77a9a4a7289..2faf6a9c403d5 100644 --- a/docs/generated/cli/graph.md +++ b/docs/generated/cli/graph.md @@ -69,44 +69,64 @@ nx graph --watch ### exclude +Type: array + List of projects delimited by commas to exclude from the project graph. ### file +Type: string + Output file (e.g. --file=output.json or --file=dep-graph.html) ### focus +Type: string + Use to show the project graph for a particular project and every node that is either an ancestor or a descendant. ### groupByFolder +Type: boolean + Group projects by folder in the project graph ### help +Type: boolean + Show help ### host +Type: string + Bind the project graph server to a specific ip address. ### open -Default: `true` +Type: boolean + +Default: true Open the project graph in the browser. ### port +Type: number + Bind the project graph server to a specific port. ### version +Type: boolean + Show version number ### watch -Default: `false` +Type: boolean + +Default: false Watch for changes to project graph and update in-browser diff --git a/docs/generated/cli/list.md b/docs/generated/cli/list.md index e45179f064c0d..ff79d1196a7df 100644 --- a/docs/generated/cli/list.md +++ b/docs/generated/cli/list.md @@ -33,12 +33,18 @@ nx list @nrwl/web ### help +Type: boolean + Show help ### plugin +Type: string + The name of an installed plugin to query ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/migrate.md b/docs/generated/cli/migrate.md index d079468b5ed1a..dca44316d86cf 100644 --- a/docs/generated/cli/migrate.md +++ b/docs/generated/cli/migrate.md @@ -63,24 +63,36 @@ nx migrate --run-migrations=migrations.json ### from +Type: string + Use the provided versions for packages instead of the ones installed in node_modules (e.g., --from="@nrwl/react:12.0.0,@nrwl/js:12.0.0") ### help +Type: boolean + Show help ### packageAndVersion +Type: string + The target package and version (e.g, @nrwl/workspace@13.0.0) ### runMigrations +Type: string + Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json) ### to +Type: string + Use the provided versions for packages instead of the ones calculated by the migrator (e.g., --to="@nrwl/react:12.0.0,@nrwl/js:12.0.0") ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/print-affected.md b/docs/generated/cli/print-affected.md index cfe647da58450..58b6b19f1ba57 100644 --- a/docs/generated/cli/print-affected.md +++ b/docs/generated/cli/print-affected.md @@ -51,37 +51,53 @@ nx print-affected --target=build --select=tasks.target.project ### all +Type: boolean + All projects ### base +Type: string + Base of the current branch (usually main) ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### files +Type: array + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +Type: string + Latest commit of the current branch (usually HEAD) ### help +Type: boolean + Show help ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -89,24 +105,34 @@ Isolate projects which previously failed ### runner +Type: string + This is the name of the tasks runner configured in nx.json ### select +Type: string + Select the subset of the returned json document (e.g., --selected=projects) ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +Type: boolean + Uncommitted changes ### untracked +Type: boolean + Untracked changes ### verbose @@ -115,4 +141,6 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number diff --git a/docs/generated/cli/run-many.md b/docs/generated/cli/run-many.md index 5c58a71ab193c..9fe8646d25f05 100644 --- a/docs/generated/cli/run-many.md +++ b/docs/generated/cli/run-many.md @@ -39,25 +39,35 @@ nx run-many --target=test --projects=proj1,proj2 --parallel=2 ### all +Type: boolean + Run the target on all projects in the workspace ### configuration +Type: string + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +Type: array + +Default: Exclude certain projects from being processed ### help +Type: boolean + Show help ### ~~only-failed~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15. @@ -65,24 +75,34 @@ Only run the target on projects which previously failed ### parallel +Type: string + Max number of parallel processes [default is 3] ### projects +Type: string + Projects to run (comma delimited) ### runner +Type: string + Override the tasks runner in `nx.json` ### skip-nx-cache -Default: `false` +Type: boolean + +Default: false Rerun the tasks even when the results are available in the cache ### target +Type: string + Task to run for affected projects ### verbose @@ -91,11 +111,15 @@ Print additional error stack trace on failure ### version +Type: boolean + Show version number ### ~~with-deps~~ -Default: `false` +Type: boolean + +Default: false **Deprecated:** Configure target dependencies instead. It will be removed in v14. diff --git a/docs/generated/cli/workspace-generator.md b/docs/generated/cli/workspace-generator.md index 3fda1aa5622fb..9349ffbde8654 100644 --- a/docs/generated/cli/workspace-generator.md +++ b/docs/generated/cli/workspace-generator.md @@ -19,16 +19,24 @@ nx workspace-generator [name] ### help +Type: boolean + Show help ### list-generators +Type: boolean + List the available workspace-generators ### name +Type: string + The name of your generator ### version +Type: boolean + Show version number diff --git a/scripts/documentation/utils.ts b/scripts/documentation/utils.ts index aa817a59813ea..c219fa1699fd6 100644 --- a/scripts/documentation/utils.ts +++ b/scripts/documentation/utils.ts @@ -124,6 +124,8 @@ export interface ParsedCommand { options?: Array; } +const YargsTypes = ['array', 'count', 'string', 'boolean', 'number']; + export async function parseCommand( name: string, command: any @@ -152,10 +154,17 @@ export async function parseCommand( .getInternalMethods() .getUsageInstance() .getDescriptions(); - const builderDefaultOptions = builder.getOptions().default; - const builderAutomatedOptions = builder.getOptions().defaultDescription; + const builderOptions = builder.getOptions(); + const builderDefaultOptions = builderOptions.default; + const builderAutomatedOptions = builderOptions.defaultDescription; const builderDeprecatedOptions = builder.getDeprecatedOptions(); - const builderOptionsChoices = builder.getOptions().choices; + const builderOptionsChoices = builderOptions.choices; + const builderOptionTypes = YargsTypes.reduce((acc, type) => { + builderOptions[type].forEach( + (option) => (acc = { ...acc, [option]: type }) + ); + return acc; + }, {}); return { name, @@ -168,6 +177,7 @@ export async function parseCommand( ? builderDescriptions[key].replace('__yargsString__:', '') : '', default: builderDefaultOptions[key] ?? builderAutomatedOptions[key], + type: builderOptionTypes[key], choices: builderOptionsChoices[key], deprecated: builderDeprecatedOptions[key], })) || null, @@ -177,26 +187,25 @@ export async function parseCommand( export function generateOptionsMarkdown(command): string { let response = ''; if (Array.isArray(command.options) && !!command.options.length) { - response += '\n## Options'; + response += '\n## Options\n'; command.options .sort((a, b) => sortAlphabeticallyFunction(a.name, b.name)) .forEach((option) => { response += dedent` - ### ${option.deprecated ? `~~${option.name}~~` : option.name} - ${ - option.default === undefined || option.default === '' - ? '' - : `Default: \`${option.default}\`\n` - }`; - response += dedent` - ${ - option.choices === undefined - ? '' - : `Choices: \`[${option.choices - .map((c) => `"${c}"`) - .join(', ')}]\`\n` - }`; + ### ${option.deprecated ? `~~${option.name}~~` : option.name} + `; + if (option.type !== undefined && option.type !== '') { + response += `Type: ${option.type}\n`; + } + if (option.choices !== undefined) { + response += dedent` + Choices: [${option.choices.map((c) => `"${c}"`).join(', ')}]\n`; + } + if (option.default !== undefined && option.default !== '') { + response += dedent` + Default: ${option.default}\n`; + } response += dedent` ${formatDeprecated(option.description, option.deprecated)} `;