Merge pull request #326 from michaeltlombardi/docs/main/option-refactor

(DOCS) Options refactor

CHANGELOG.md

@@ -30,19 +30,30 @@ changes since the last release, see the [diff on GitHub][unreleased].
 
 - Updated the options for the `dsc` root command:
 
-  - The short name for the [--format][36] option, which controls the output format, is now `-o`
-    instead of `-f`.
-  - The `--logging-level` option is renamed to [--trace-level][37] with the short name `-l`. The
+  - Removed the global `--format` option, which controls the output format. Now, the relevant
+    subcommands that return formattable output have the `--format` option (short option as `-f`)
+    added to them.
+  - Removed the global `--input` and `--input-file` options. Now, the `config` subcommands have the
+    `--document` and `--path` options for specifying the configuration document as a string or from
+    a file. The relevant `resource` subcommands have the `--input` and `--path` options for
+    specifying the instance properties as a string or from a file.
+  - The `--logging-level` option is renamed to [--trace-level][36] with the short name `-l`. The
     default trace level is now `warning` instead of `info`.
-  - Added the [--trace-format][38] option with the `-f` short name. This option enables you to
+  - Added the [--trace-format][37] option with the `-f` short name. This option enables you to
     choose the format for the trace messages emitted to stderr. By default, the messages are
     emitted as lines of text with console colors. You can set this option to `plaintext` to emit
     the messages without console colors or to `json` to emit the messages as JSON objects.
 
   <details><summary>Related work items</summary>
 
-  - Issues: [#286][#286]
-  - PRs: [#299][#299]
+  - Issues:
+    - [#286][#286]
+    - [#227][#227]
+    - [#226][#226]
+  - PRs:
+    - [#299][#299]
+    - [#303][#303]
+    - [#305][#305]
 
   </details>
 
@@ -526,9 +537,8 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [33]: docs/reference/cli/config/command.md#-p---parameters
 [34]: docs/reference/cli/config/command.md#-f---parameters_file
 [35]: docs/reference/cli/config/command.md
-[36]: docs/reference/cli/dsc.md#-o---format
-[37]: docs/reference/cli/dsc.md#-l---trace-level
-[38]: docs/reference/cli/dsc.md#-f---trace-format
+[36]: docs/reference/cli/dsc.md#-l---trace-level
+[37]: docs/reference/cli/dsc.md#-f---trace-format
 
 <!-- Issue and PR links -->
 [#107]: https://github.com/PowerShell/DSC/issues/107
@@ -565,6 +575,8 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [#215]: https://github.com/PowerShell/DSC/issues/215
 [#216]: https://github.com/PowerShell/DSC/issues/216
 [#217]: https://github.com/PowerShell/DSC/issues/217
+[#226]: https://github.com/PowerShell/DSC/issues/226
+[#227]: https://github.com/PowerShell/DSC/issues/227
 [#240]: https://github.com/PowerShell/DSC/issues/240
 [#241]: https://github.com/PowerShell/DSC/issues/241
 [#248]: https://github.com/PowerShell/DSC/issues/248
@@ -573,6 +585,8 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [#291]: https://github.com/PowerShell/DSC/issues/291
 [#294]: https://github.com/PowerShell/DSC/issues/294
 [#299]: https://github.com/PowerShell/DSC/issues/299
+[#303]: https://github.com/PowerShell/DSC/issues/303
+[#305]: https://github.com/PowerShell/DSC/issues/305
 [#311]: https://github.com/PowerShell/DSC/issues/311
 [#45]:  https://github.com/PowerShell/DSC/issues/45
 [#49]:  https://github.com/PowerShell/DSC/issues/49

docs/reference/cli/config/export.md

@@ -13,18 +13,36 @@ Generates a configuration document that defines the existing instances of a set
 
 ## Syntax
 
+### Configuration document from stdin
+
+```sh
+<document-string> | dsc config export [Options]
+```
+
+### Configuration document from option string
+
 ```sh
-dsc config export [Options]
+dsc config export [Options] --document <document-string>
+```
+
+### Configuration document from file
+
+```sh
+dsc config export [Options] --path <document-filepath>
 ```
 
 ## Description
 
 The `export` subcommand generates a configuration document that includes every instance of a set of
-resources. This command expects a configuration document formatted as JSON or YAML over stdin. The
-input configuration defines the resources to export. DSC ignores any properties specified for the
-resources in the input configuration for the operation, but the input document and any properties
-for resource instances must still validate against the configuration document and resource instance
-schemas.
+resources.
+
+The configuration document must be passed to this command as JSON or YAML over stdin, as a string
+with the **document** option, or from a file with the **path** option.
+
+The input configuration defines the resources to export. DSC ignores any properties specified for
+the resources in the input configuration for the operation, but the input document and any
+properties for resource instances must still validate against the configuration document and
+resource instance schemas.
 
 Only specify resources with a resource manifest that defines the [export][01] section in the input
 configuration. Only define each resource type once. If the configuration document includes any
@@ -33,6 +51,48 @@ configuration, DSC raises an error.
 
 ## Options
 
+### -d, --document
+
+Specifies the configuration document to export from as a JSON or YAML object. DSC validates the
+document against the configuration document schema. If the validation fails, DSC raises an error.
+
+This option can't be used with configuration document over stdin or the `--path` option. Choose
+whether to pass the configuration document to the command over stdin, from a file with the `--path`
+option, or with the `--document` option.
+
+```yaml
+Type:      String
+Mandatory: false
+```
+
+### -p, --path
+
+Defines the path to a configuration document to export instead of piping the document from stdin or
+passing it as a string with the `--document` option. The specified file must contain a
+configuration document as a JSON or YAML object. DSC validates the document against the
+configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC
+raises an error.
+
+This option is mutually exclusive with the `--document` option. When you use this option, DSC
+ignores any input from stdin.
+
+```yaml
+Type:      String
+Mandatory: false
+```
+
+### -f, --format
+
+The `--format` option controls the console output format for the command. If the command output is
+redirected or captured as a variable, the output is always JSON.
+
+```yaml
+Type:         String
+Mandatory:    false
+DefaultValue: yaml
+ValidValues:  [json, pretty-json, yaml]
+```
+
 ### -h, --help
 
 Displays the help for the current command or subcommand. When you specify this option, the

docs/reference/cli/config/get.md

@@ -13,8 +13,22 @@ Retrieves the current state of resource instances in a configuration document.
 
 ## Syntax
 
+### Configuration document from stdin
+
+```sh
+<document-string> | dsc config get [Options]
+```
+
+### Configuration document from option string
+
+```sh
+dsc config get [Options] --document <document-string>
+```
+
+### Configuration document from file
+
 ```sh
-dsc config get [Options]
+dsc config get [Options] --path <document-filepath>
 ```
 
 ## Description
@@ -23,7 +37,8 @@ The `get` subcommand returns the current state of the resource instances in a co
 document. When this command runs, DSC validates the configuration document before invoking the get
 operation for each resource instance defined in the document.
 
-The configuration document must be passed to this command as JSON or YAML over stdin.
+The configuration document must be passed to this command as JSON or YAML over stdin, as a string
+with the **document** option, or from a file with the **path** option.
 
 ## Examples
 
@@ -60,24 +75,67 @@ cat ./example.dsc.config.yaml | dsc config get
 
 ### Example 2 - Passing a file to read as the configuration document
 
-The command uses the [--input-file][01] global option to retrieve the resource instances defined in
-the `example.dsc.config.yaml` file.
+The command uses the **path** option to retrieve the resource instances defined in the
+`example.dsc.config.yaml` file.
 
 ```sh
-dsc --input-file ./example.dsc.config.yaml config get
+dsc config get --path ./example.dsc.config.yaml
 ```
 
 ### Example 3 - Passing a configuration document as a variable
 
-The command uses the [--input][02] global option to retrieve the resource instances defined in a
+The command uses the **document** option to retrieve the resource instances defined in a
 configuration document stored in the `$desired` variable.
 
 ```sh
-dsc --input $desired config get
+dsc config get --document $desired
 ```
 
 ## Options
 
+### -d, --document
+
+Specifies the configuration document to retrieve actual state for. The document must be a string
+containing a JSON or YAML object. DSC validates the document against the configuration document
+schema. If the validation fails, DSC raises an error.
+
+This option can't be used with configuration document over stdin or the `--path` option. Choose
+whether to pass the configuration document to the command over stdin, from a file with the `--path`
+option, or with the `--document` option.
+
+```yaml
+Type:      String
+Mandatory: false
+```
+
+### -p, --path
+
+Defines the path to a configuration document to retrieve actual state for instead of piping the
+document from stdin or passing it as a string with the `--document` option. The specified file must
+contain a configuration document as a JSON or YAML object. DSC validates the document against the
+configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC
+raises an error.
+
+This option is mutually exclusive with the `--document` option. When you use this option, DSC
+ignores any input from stdin.
+
+```yaml
+Type:      String
+Mandatory: false
+```
+
+### -f, --format
+
+The `--format` option controls the console output format for the command. If the command output is
+redirected or captured as a variable, the output is always JSON.
+
+```yaml
+Type:         String
+Mandatory:    false
+DefaultValue: yaml
+ValidValues:  [json, pretty-json, yaml]
+```
+
 ### -h, --help
 
 Displays the help for the current command or subcommand. When you specify this option, the
@@ -92,8 +150,6 @@ Mandatory: false
 
 This command returns JSON output that includes whether the operation or any resources raised any
 errors, the collection of messages emitted during the operation, and the get operation results for
-every instance. For more information, see [dsc config get result schema][03].
+every instance. For more information, see [dsc config get result schema][01].
 
-[01]: ../dsc.md#-p---input-file
-[02]: ../dsc.md#-i---input
-[03]: ../../schemas/outputs/config/get.md
+[01]: ../../schemas/outputs/config/get.md

docs/reference/cli/config/set.md

@@ -13,8 +13,22 @@ Enforces the desired state of resource instances in a configuration document.
 
 ## Syntax
 
+### Configuration document from stdin
+
+```sh
+<document-string> | dsc config set [Options]
+```
+
+### Configuration document from option string
+
+```sh
+dsc config set [Options] --document <document-string>
+```
+
+### Configuration document from file
+
 ```sh
-dsc config set [Options]
+dsc config set [Options] --path <document-filepath>
 ```
 
 ## Description
@@ -24,7 +38,8 @@ document. When this command runs, DSC validates the configuration document befor
 operation for each resource instance defined in the document. DSC then invokes the set operation
 for each resource instance that isn't in the desired state.
 
-The configuration document must be passed to this command as JSON or YAML over stdin.
+The configuration document must be passed to this command as JSON or YAML over stdin, as a string
+with the **document** option, or from a file with the **path** option.
 
 ## Examples
 
@@ -61,24 +76,67 @@ cat ./example.dsc.config.yaml | dsc config set
 
 ### Example 2 - Passing a file to read as the configuration document
 
-The command uses the [--input-file][01] global option to enforce the configuration defined in
-the `example.dsc.config.yaml` file.
+The command uses the **path** option to enforce the configuration defined in the
+`example.dsc.config.yaml` file.
 
 ```sh
-dsc --input-file ./example.dsc.config.yaml config set
+dsc config set --path ./example.dsc.config.yaml
 ```
 
 ### Example 3 - Passing a configuration document as a variable
 
-The command uses the [--input][02] global option to enforce the configuration stored in the
-`$desired` variable.
+The command uses the **document** option to enforce the configuration stored in the `$desired`
+variable.
 
 ```sh
-dsc --input $desired config set
+dsc config set --document $desired
 ```
 
 ## Options
 
+### -d, --document
+
+Specifies the configuration document to enforce state for. The document must be a string
+containing a JSON or YAML object. DSC validates the document against the configuration document
+schema. If the validation fails, DSC raises an error.
+
+This option can't be used with configuration document over stdin or the `--path` option. Choose
+whether to pass the configuration document to the command over stdin, from a file with the `--path`
+option, or with the `--document` option.
+
+```yaml
+Type:      String
+Mandatory: false
+```
+
+### -p, --path
+
+Defines the path to a configuration document to enforce state for instead of piping the document
+from stdin or passing it as a string with the `--document` option. The specified file must contain
+a configuration document as a JSON or YAML object. DSC validates the document against the
+configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC
+raises an error.
+
+This option is mutually exclusive with the `--document` option. When you use this option, DSC
+ignores any input from stdin.
+
+```yaml
+Type:      String
+Mandatory: false
+```
+
+### -f, --format
+
+The `--format` option controls the console output format for the command. If the command output is
+redirected or captured as a variable, the output is always JSON.
+
+```yaml
+Type:         String
+Mandatory:    false
+DefaultValue: yaml
+ValidValues:  [json, pretty-json, yaml]
+```
+
 ### -h, --help
 
 Displays the help for the current command or subcommand. When you specify this option, the
@@ -93,8 +151,6 @@ Mandatory: false
 
 This command returns JSON output that includes whether the operation or any resources raised any
 errors, the collection of messages emitted during the operation, and the set operation results for
-every instance. For more information, see [dsc config get result schema][03].
+every instance. For more information, see [dsc config get result schema][01].
 
-[01]: ../dsc.md#-p---input-file
-[02]: ../dsc.md#-i---input
-[03]: ../../schemas/outputs/config/set.md
+[01]: ../../schemas/outputs/config/set.md