From fa00d50e73d31583895445c067144a8f391842c7 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Wed, 24 Oct 2018 13:37:54 -0700 Subject: [PATCH 1/6] docs: edit and expand command docs --- packages/angular/cli/commands/build-long.md | 12 +++++++++++- packages/angular/cli/commands/config.json | 2 +- packages/angular/cli/commands/definitions.json | 8 ++++---- packages/angular/cli/commands/lint-long.md | 4 +++- packages/angular/cli/commands/lint.json | 2 +- packages/angular/cli/commands/new.json | 4 ++-- packages/angular/cli/commands/run-long.md | 8 ++++++++ packages/angular/cli/commands/run.json | 6 +++--- 8 files changed, 33 insertions(+), 13 deletions(-) create mode 100644 packages/angular/cli/commands/run-long.md diff --git a/packages/angular/cli/commands/build-long.md b/packages/angular/cli/commands/build-long.md index 0d04d981498a..70d51e2e0852 100644 --- a/packages/angular/cli/commands/build-long.md +++ b/packages/angular/cli/commands/build-long.md @@ -1,3 +1,13 @@ +Uses the Webpack build tool, with default target environment and build options specified in the workspace configuration file, `angular.json`. + +You can override the configuration defaults by specifying an option on the command line. +The command can accept option names given in either dash-case or camelCase. +Note that in the configuration file, you must specify names in camelCase. + +The configuration options generally correspond to the command options. +Some additional options can only be set through the configuration file, +either by direct editing or with the `ng config` command. +These include `assets`, `styles`, and `scripts` objects that provide runtime-global resources to include in the project. Resources in CSS, such as images and fonts, are automatically written and fingerprinted at the root of the output folder. -Uses the Webpack build tool, with environment and build options specified in the CLI configuration file. +For further details, see Workspace Configuration. diff --git a/packages/angular/cli/commands/config.json b/packages/angular/cli/commands/config.json index 8d1dabb3f4ed..d0c3d59520b3 100644 --- a/packages/angular/cli/commands/config.json +++ b/packages/angular/cli/commands/config.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/schema", "$id": "ng-cli://commands/config.json", - "description": "Retrieves or sets Angular configuration values.", + "description": "Retrieves or sets Angular configuration values in the angular.json file for the workspace.", "$longDescription": "", "$aliases": [], diff --git a/packages/angular/cli/commands/definitions.json b/packages/angular/cli/commands/definitions.json index ee2f5b011793..094a7d7a7b71 100644 --- a/packages/angular/cli/commands/definitions.json +++ b/packages/angular/cli/commands/definitions.json @@ -14,14 +14,14 @@ } }, "configuration": { - "description": "A named configuration environment, as specified in the \"configurations\" section of angular.json.", + "description": "A named build target, as specified in the \"configurations\" section of angular.json.\nEach named target is accompanied by a configuration of option defaults for that target.", "type": "string", "aliases": [ "c" ] }, "prod": { - "description": "When true, sets the build configuration to the production environment.\nAll builds make use of bundling and limited tree-shaking, A production build also runs limited dead code elimination using UglifyJS.", + "description": "When true, sets the build configuration to the production target.\nAll builds make use of bundling and limited tree-shaking, A production build also runs limited dead code elimination using UglifyJS.", "type": "boolean" } } @@ -42,13 +42,13 @@ "type": "boolean", "default": false, "aliases": [ "d" ], - "description": "When true, run through and report activity without writing out results." + "description": "When true, runs through and reports activity without writing out results." }, "force": { "type": "boolean", "default": false, "aliases": [ "f" ], - "description": "When true, force overwriting of existing files." + "description": "When true, forces overwriting of existing files." }, "interactive": { "type": "boolean", diff --git a/packages/angular/cli/commands/lint-long.md b/packages/angular/cli/commands/lint-long.md index 5b6eb99d0d73..42bbc32f0051 100644 --- a/packages/angular/cli/commands/lint-long.md +++ b/packages/angular/cli/commands/lint-long.md @@ -1,2 +1,4 @@ Takes the name of the project, as specified in the `projects` section of the `angular.json` workspace configuration file. -When a project name is not supplied, uses the configured `defaultProject` of the workspace. \ No newline at end of file +When a project name is not supplied, uses the configured `defaultProject` of the workspace. + +The default linting tool is [TSLint](https://palantir.github.io/tslint/), and the default configuration is specified in the project's `tslint.json` file. \ No newline at end of file diff --git a/packages/angular/cli/commands/lint.json b/packages/angular/cli/commands/lint.json index 3c409083bc39..eed1cda035c6 100644 --- a/packages/angular/cli/commands/lint.json +++ b/packages/angular/cli/commands/lint.json @@ -22,7 +22,7 @@ } }, "configuration": { - "description": "Specify the configuration to use.", + "description": "The linting configuration to use.", "type": "string", "aliases": [ "c" diff --git a/packages/angular/cli/commands/new.json b/packages/angular/cli/commands/new.json index 80a8d35623b6..aeffbfe5255f 100644 --- a/packages/angular/cli/commands/new.json +++ b/packages/angular/cli/commands/new.json @@ -16,13 +16,13 @@ "collection": { "type": "string", "aliases": [ "c" ], - "description": "Schematics collection to use." + "description": "A collection of schematics to use in generating the initial app." }, "verbose": { "type": "boolean", "default": false, "aliases": [ "v" ], - "description": "Adds more details to output logging." + "description": "When true, adds more details to output logging." } }, "required": [] diff --git a/packages/angular/cli/commands/run-long.md b/packages/angular/cli/commands/run-long.md new file mode 100644 index 000000000000..7db565352207 --- /dev/null +++ b/packages/angular/cli/commands/run-long.md @@ -0,0 +1,8 @@ +Architect is the tool that the CLI uses to perform complex tasks such as compilation, according to provided configurations. +The CLI commands run Architect targets such as `build`, `serve`, `test` and `lint`. +Each named target has a default configuration, specified by an "options" object, and an optional set of named alternate configurations in the "configurations" object. +For example, the "build" target for a newly generated app has a predefined alternate configuration named "production". + +You can define new targets and their configuration options in the "architect" section of the `angular.json` file. +If you do so, you can run them from the command line using the `ng run` command. + diff --git a/packages/angular/cli/commands/run.json b/packages/angular/cli/commands/run.json index e14547ed1133..1f7397496c46 100644 --- a/packages/angular/cli/commands/run.json +++ b/packages/angular/cli/commands/run.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/schema", "$id": "ng-cli://commands/run.json", - "description": "Runs a custom target defined in your project.", + "description": "Runs an architect target with a custom build configuration defined in your project.", "$longDescription": "", "$aliases": [], @@ -15,14 +15,14 @@ "properties": { "target": { "type": "string", - "description": "The target to run.", + "description": "The command to run.", "$default": { "$source": "argv", "index": 0 } }, "configuration": { - "description": "Specify the configuration to use.", + "description": "A named build configuration, defined in the \"configurations\" section of angular.json.\nThe build uses the configuration associated with the given target.", "type": "string", "aliases": [ "c" ] } From d039c8aaced42610656bde15858d4a747466522c Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Thu, 25 Oct 2018 08:34:33 -0700 Subject: [PATCH 2/6] docs: edit run terminology --- packages/angular/cli/commands/run-long.md | 3 +-- packages/angular/cli/commands/run.json | 8 ++++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/packages/angular/cli/commands/run-long.md b/packages/angular/cli/commands/run-long.md index 7db565352207..22404bf5a291 100644 --- a/packages/angular/cli/commands/run-long.md +++ b/packages/angular/cli/commands/run-long.md @@ -4,5 +4,4 @@ Each named target has a default configuration, specified by an "options" object, For example, the "build" target for a newly generated app has a predefined alternate configuration named "production". You can define new targets and their configuration options in the "architect" section of the `angular.json` file. -If you do so, you can run them from the command line using the `ng run` command. - +If you do so, you can run them from the command line using the `ng run` command. \ No newline at end of file diff --git a/packages/angular/cli/commands/run.json b/packages/angular/cli/commands/run.json index 1f7397496c46..673cca89f74c 100644 --- a/packages/angular/cli/commands/run.json +++ b/packages/angular/cli/commands/run.json @@ -1,8 +1,8 @@ { "$schema": "http://json-schema.org/schema", "$id": "ng-cli://commands/run.json", - "description": "Runs an architect target with a custom build configuration defined in your project.", - "$longDescription": "", + "description": "Runs an architect target with a custom builder configuration defined in your project.", + "$longDescription": "./run-long.md", "$aliases": [], "$scope": "in", @@ -15,14 +15,14 @@ "properties": { "target": { "type": "string", - "description": "The command to run.", + "description": "The target to run.", "$default": { "$source": "argv", "index": 0 } }, "configuration": { - "description": "A named build configuration, defined in the \"configurations\" section of angular.json.\nThe build uses the configuration associated with the given target.", + "description": "A named builder configuration, defined in the \"configurations\" section of angular.json.\nThe builder uses the named configuration to run the given target.", "type": "string", "aliases": [ "c" ] } From 239a217e418ba6c913c33878768648cc5a613258 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Mon, 29 Oct 2018 12:51:46 -0700 Subject: [PATCH 3/6] docs: edit run description --- packages/angular/cli/commands/run-long.md | 19 ++++++++++++++----- packages/angular/cli/commands/run.json | 4 ++-- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/packages/angular/cli/commands/run-long.md b/packages/angular/cli/commands/run-long.md index 22404bf5a291..b68fa94fa547 100644 --- a/packages/angular/cli/commands/run-long.md +++ b/packages/angular/cli/commands/run-long.md @@ -1,7 +1,16 @@ Architect is the tool that the CLI uses to perform complex tasks such as compilation, according to provided configurations. -The CLI commands run Architect targets such as `build`, `serve`, `test` and `lint`. -Each named target has a default configuration, specified by an "options" object, and an optional set of named alternate configurations in the "configurations" object. -For example, the "build" target for a newly generated app has a predefined alternate configuration named "production". +The CLI commands run Architect targets such as `build`, `serve`, `test` and `lint`. +Each named target has a default configuration, specified by an "options" object, +and an optional set of named alternate configurations in the "configurations" object. -You can define new targets and their configuration options in the "architect" section of the `angular.json` file. -If you do so, you can run them from the command line using the `ng run` command. \ No newline at end of file +For example, the "server" target for a newly generated app has a predefined +alternate configuration named "production". + +You can define new targets and their configuration options in the "architect" section +of the `angular.json` file. +If you do so, you can run them from the command line using the `ng run` command. +Execute the command using the following format. + +``` +ng run project:target[.configuration] +``` \ No newline at end of file diff --git a/packages/angular/cli/commands/run.json b/packages/angular/cli/commands/run.json index 673cca89f74c..86f132f8f1b1 100644 --- a/packages/angular/cli/commands/run.json +++ b/packages/angular/cli/commands/run.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/schema", "$id": "ng-cli://commands/run.json", - "description": "Runs an architect target with a custom builder configuration defined in your project.", + "description": "Runs an architect target with an optional custom builder configuration defined in your project.", "$longDescription": "./run-long.md", "$aliases": [], @@ -15,7 +15,7 @@ "properties": { "target": { "type": "string", - "description": "The target to run.", + "description": "The Architect target to run.", "$default": { "$source": "argv", "index": 0 From d779ff03fa6ed44a2d34252bf8896a0176565222 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Mon, 29 Oct 2018 13:00:20 -0700 Subject: [PATCH 4/6] docs: edit build description --- packages/angular/cli/commands/build-long.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/angular/cli/commands/build-long.md b/packages/angular/cli/commands/build-long.md index 70d51e2e0852..c2fa222a7f8a 100644 --- a/packages/angular/cli/commands/build-long.md +++ b/packages/angular/cli/commands/build-long.md @@ -1,10 +1,11 @@ -Uses the Webpack build tool, with default target environment and build options specified in the workspace configuration file, `angular.json`. +Uses the Webpack build tool, with default configuration options specified in the workspace configuration file, `angular.json`, or with a named alternative configuration. +A "production" configuration is created by default when you use the CLI to create the project, and you can use that configuration by specifying the `--prod` option. -You can override the configuration defaults by specifying an option on the command line. +The configuration options generally correspond to the command options. +You can override individual configuration defaults by specifying the corresponding options on the command line. The command can accept option names given in either dash-case or camelCase. Note that in the configuration file, you must specify names in camelCase. -The configuration options generally correspond to the command options. Some additional options can only be set through the configuration file, either by direct editing or with the `ng config` command. These include `assets`, `styles`, and `scripts` objects that provide runtime-global resources to include in the project. From beed6433496e8dd5c73c1ab591ee72d54384ba4f Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Tue, 30 Oct 2018 09:45:24 -0700 Subject: [PATCH 5/6] docs: remove uglify reference --- packages/angular/cli/commands/definitions.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/angular/cli/commands/definitions.json b/packages/angular/cli/commands/definitions.json index 094a7d7a7b71..504f23b9ea23 100644 --- a/packages/angular/cli/commands/definitions.json +++ b/packages/angular/cli/commands/definitions.json @@ -21,7 +21,7 @@ ] }, "prod": { - "description": "When true, sets the build configuration to the production target.\nAll builds make use of bundling and limited tree-shaking, A production build also runs limited dead code elimination using UglifyJS.", + "description": "When true, sets the build configuration to the production target.\nAll builds make use of bundling and limited tree-shaking, A production build also runs limited dead code elimination.", "type": "boolean" } } From c6d296aaacc2825cb00fc0df7ab16d09263950e6 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Tue, 30 Oct 2018 09:49:35 -0700 Subject: [PATCH 6/6] docs: fix run syntax --- packages/angular/cli/commands/run-long.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/angular/cli/commands/run-long.md b/packages/angular/cli/commands/run-long.md index b68fa94fa547..8f84cf47994a 100644 --- a/packages/angular/cli/commands/run-long.md +++ b/packages/angular/cli/commands/run-long.md @@ -12,5 +12,5 @@ If you do so, you can run them from the command line using the `ng run` command. Execute the command using the following format. ``` -ng run project:target[.configuration] +ng run project:target[:configuration] ``` \ No newline at end of file