From 796c70d272670dad69fbe3599268dd97ad4c69bc Mon Sep 17 00:00:00 2001 From: Miroslav Jonas Date: Wed, 30 Mar 2022 12:47:26 +0200 Subject: [PATCH] feat(nxdev): add types to CLI docs --- 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 +++ nx-dev/feature-doc-viewer/src/lib/content.tsx | 3 ++ .../src/lib/ui/markdown/markdown.tsx | 3 ++ scripts/documentation/utils.ts | 45 ++++++++++------- 18 files changed, 384 insertions(+), 55 deletions(-) diff --git a/docs/generated/cli/affected-apps.md b/docs/generated/cli/affected-apps.md index 2849cdc215efff..da6ade74d1ca92 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 +_boolean_ + All projects ### base +_string_ + Base of the current branch (usually main) ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### files +_array_ + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +_string_ + Latest commit of the current branch (usually HEAD) ### help +_boolean_ + Show help ### ~~only-failed~~ -Default: `false` +_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 +_string_ + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +_boolean_ + Uncommitted changes ### untracked +_boolean_ + Untracked changes ### verbose @@ -103,4 +127,6 @@ Print additional error stack trace on failure ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/affected-graph.md b/docs/generated/cli/affected-graph.md index ba409666b2fad7..645b1c1c99ba01 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 +_boolean_ + All projects ### base +_string_ + Base of the current branch (usually main) ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### file +_string_ + Output file (e.g. --file=output.json or --file=dep-graph.html) ### files +_array_ + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### focus +_string_ + Use to show the project graph for a particular project and every node that is either an ancestor or a descendant. ### groupByFolder +_boolean_ + Group projects by folder in the project graph ### head +_string_ + Latest commit of the current branch (usually HEAD) ### help +_boolean_ + Show help ### host +_string_ + Bind the project graph server to a specific ip address. ### ~~only-failed~~ -Default: `false` +_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` +_boolean_ + +Default: true Open the project graph in the browser. ### port +_number_ + Bind the project graph server to a specific port. ### runner +_string_ + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +_boolean_ + Uncommitted changes ### untracked +_boolean_ + Untracked changes ### verbose @@ -143,10 +179,14 @@ Print additional error stack trace on failure ### version +_boolean_ + Show version number ### watch -Default: `false` +_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 27bab31a502bdd..9246c55c98abc7 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 +_boolean_ + All projects ### base +_string_ + Base of the current branch (usually main) ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### files +_array_ + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +_string_ + Latest commit of the current branch (usually HEAD) ### help +_boolean_ + Show help ### ~~only-failed~~ -Default: `false` +_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 +_string_ + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +_boolean_ + Uncommitted changes ### untracked +_boolean_ + Untracked changes ### verbose @@ -103,4 +127,6 @@ Print additional error stack trace on failure ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/affected.md b/docs/generated/cli/affected.md index 31c8b5d9515eae..cdcc58a62533b7 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 +_boolean_ + All projects ### base +_string_ + Base of the current branch (usually main) ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### files +_array_ + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +_string_ + Latest commit of the current branch (usually HEAD) ### help +_boolean_ + Show help ### ~~only-failed~~ -Default: `false` +_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 +_string_ + Max number of parallel processes [default is 3] ### runner +_string_ + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### target +_string_ + Task to run for affected projects ### uncommitted +_boolean_ + Uncommitted changes ### untracked +_boolean_ + Untracked changes ### verbose @@ -125,4 +153,6 @@ Print additional error stack trace on failure ### version +_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 bc65d4a7bb2729..7015515f051122 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 +_boolean_ + Show help ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/create-nx-workspace.md b/docs/generated/cli/create-nx-workspace.md index 5f0fa095daeb55..a6a5d65bf67661 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` +_boolean_ + +Default: false Show all prompts ### appName +_string_ + The name of the application when a preset with pregenerated app is selected ### cli -Choices: `["nx", "angular"]` +_string_ + +Choices: ["nx", "angular"] CLI to power the Nx workspace ### defaultBase -Default: `main` +_string_ + +Default: main Default base to use for new projects ### help +_boolean_ + Show help ### interactive +_boolean_ + Enable interactive mode with presets ### name +_string_ + Workspace name (e.g. org name) ### nxCloud -Default: `true` +_boolean_ + +Default: true Use Nx Cloud ### packageManager -Default: `npm` +_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"]` +_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 +_string_ + Style option to be used when a preset with pregenerated app is selected ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/daemon.md b/docs/generated/cli/daemon.md index 51de33da34ea4d..5f74d71d7f1c1b 100644 --- a/docs/generated/cli/daemon.md +++ b/docs/generated/cli/daemon.md @@ -19,12 +19,18 @@ nx daemon ### background -Default: `true` +_boolean_ + +Default: true ### help +_boolean_ + Show help ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/format-check.md b/docs/generated/cli/format-check.md index cf036cf7991e2a..8a3c81f0fbf1c2 100644 --- a/docs/generated/cli/format-check.md +++ b/docs/generated/cli/format-check.md @@ -19,41 +19,59 @@ nx format:check ### all +_boolean_ + All projects ### base +_string_ + Base of the current branch (usually main) ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### files +_array_ + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +_string_ + Latest commit of the current branch (usually HEAD) ### help +_boolean_ + Show help ### libs-and-apps +_boolean_ + Format only libraries and applications files. ### ~~only-failed~~ -Default: `false` +_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 +_array_ + Projects to format (comma delimited) ### runner +_string_ + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +_boolean_ + Uncommitted changes ### untracked +_boolean_ + Untracked changes ### verbose @@ -87,4 +115,6 @@ Print additional error stack trace on failure ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/format-write.md b/docs/generated/cli/format-write.md index 19bad53591dcdc..237d8a01d0b588 100644 --- a/docs/generated/cli/format-write.md +++ b/docs/generated/cli/format-write.md @@ -19,41 +19,59 @@ nx format:write ### all +_boolean_ + All projects ### base +_string_ + Base of the current branch (usually main) ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### files +_array_ + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +_string_ + Latest commit of the current branch (usually HEAD) ### help +_boolean_ + Show help ### libs-and-apps +_boolean_ + Format only libraries and applications files. ### ~~only-failed~~ -Default: `false` +_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 +_array_ + Projects to format (comma delimited) ### runner +_string_ + This is the name of the tasks runner configured in nx.json ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +_boolean_ + Uncommitted changes ### untracked +_boolean_ + Untracked changes ### verbose @@ -87,4 +115,6 @@ Print additional error stack trace on failure ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/graph.md b/docs/generated/cli/graph.md index 9c77a9a4a7289f..1c4bfb317a21db 100644 --- a/docs/generated/cli/graph.md +++ b/docs/generated/cli/graph.md @@ -69,44 +69,64 @@ nx graph --watch ### exclude +_array_ + List of projects delimited by commas to exclude from the project graph. ### file +_string_ + Output file (e.g. --file=output.json or --file=dep-graph.html) ### focus +_string_ + Use to show the project graph for a particular project and every node that is either an ancestor or a descendant. ### groupByFolder +_boolean_ + Group projects by folder in the project graph ### help +_boolean_ + Show help ### host +_string_ + Bind the project graph server to a specific ip address. ### open -Default: `true` +_boolean_ + +Default: true Open the project graph in the browser. ### port +_number_ + Bind the project graph server to a specific port. ### version +_boolean_ + Show version number ### watch -Default: `false` +_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 e45179f064c0da..f226b699b62280 100644 --- a/docs/generated/cli/list.md +++ b/docs/generated/cli/list.md @@ -33,12 +33,18 @@ nx list @nrwl/web ### help +_boolean_ + Show help ### plugin +_string_ + The name of an installed plugin to query ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/migrate.md b/docs/generated/cli/migrate.md index d079468b5ed1aa..1afeb7eba6df70 100644 --- a/docs/generated/cli/migrate.md +++ b/docs/generated/cli/migrate.md @@ -63,24 +63,36 @@ nx migrate --run-migrations=migrations.json ### from +_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 +_boolean_ + Show help ### packageAndVersion +_string_ + The target package and version (e.g, @nrwl/workspace@13.0.0) ### runMigrations +_string_ + Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json) ### to +_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 +_boolean_ + Show version number diff --git a/docs/generated/cli/print-affected.md b/docs/generated/cli/print-affected.md index cfe647da584504..f72a6287f6fc5b 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 +_boolean_ + All projects ### base +_string_ + Base of the current branch (usually main) ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### files +_array_ + Change the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas ### head +_string_ + Latest commit of the current branch (usually HEAD) ### help +_boolean_ + Show help ### ~~only-failed~~ -Default: `false` +_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 +_string_ + This is the name of the tasks runner configured in nx.json ### select +_string_ + Select the subset of the returned json document (e.g., --selected=projects) ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### uncommitted +_boolean_ + Uncommitted changes ### untracked +_boolean_ + Untracked changes ### verbose @@ -115,4 +141,6 @@ Print additional error stack trace on failure ### version +_boolean_ + Show version number diff --git a/docs/generated/cli/run-many.md b/docs/generated/cli/run-many.md index 5c58a71ab193cb..1d77b3261529a2 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 +_boolean_ + Run the target on all projects in the workspace ### configuration +_string_ + This is the configuration to use when performing tasks on projects ### exclude -Default: `` +_array_ + +Default: Exclude certain projects from being processed ### help +_boolean_ + Show help ### ~~only-failed~~ -Default: `false` +_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 +_string_ + Max number of parallel processes [default is 3] ### projects +_string_ + Projects to run (comma delimited) ### runner +_string_ + Override the tasks runner in `nx.json` ### skip-nx-cache -Default: `false` +_boolean_ + +Default: false Rerun the tasks even when the results are available in the cache ### target +_string_ + Task to run for affected projects ### verbose @@ -91,11 +111,15 @@ Print additional error stack trace on failure ### version +_boolean_ + Show version number ### ~~with-deps~~ -Default: `false` +_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 a788337885d5bf..f2ec92cdae5dc1 100644 --- a/docs/generated/cli/workspace-generator.md +++ b/docs/generated/cli/workspace-generator.md @@ -19,16 +19,24 @@ nx workspace-generator [name] ### help +_boolean_ + Show help ### list-generators +_boolean_ + List the available workspace-generators ### name +_string_ + The name of your generator` ### version +_boolean_ + Show version number diff --git a/nx-dev/feature-doc-viewer/src/lib/content.tsx b/nx-dev/feature-doc-viewer/src/lib/content.tsx index 10458f82dea585..443d047d6057d3 100644 --- a/nx-dev/feature-doc-viewer/src/lib/content.tsx +++ b/nx-dev/feature-doc-viewer/src/lib/content.tsx @@ -36,6 +36,9 @@ const components: any = (config: ComponentsConfig) => ({ ); }, + em({ children }) { + return
{children}
; + }, pre({ children }) { return <>{children}; }, diff --git a/nx-dev/feature-package-schema-viewer/src/lib/ui/markdown/markdown.tsx b/nx-dev/feature-package-schema-viewer/src/lib/ui/markdown/markdown.tsx index 3115fadc569884..5a4873d7542638 100644 --- a/nx-dev/feature-package-schema-viewer/src/lib/ui/markdown/markdown.tsx +++ b/nx-dev/feature-package-schema-viewer/src/lib/ui/markdown/markdown.tsx @@ -94,6 +94,9 @@ const components: any = (config: ComponentsConfig) => ({ ); }, + em({ children }) { + return
{children}
; + }, pre({ children }) { return <>{children}; }, diff --git a/scripts/documentation/utils.ts b/scripts/documentation/utils.ts index aa817a59813ea7..c58e8069fdcec9 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 += `*${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)} `;