dsc.exe options discoverability improvements

[JohnMcPMS]

Summary of the new feature / enhancement

As a user of dsc commands, I want to be able to know all of the options available to me without having to recursively run help on the parent commands.

For instance, to use dsc config set, I have to inquire about the options for it and dsc config and dsc.

PS> dsc config set -h
Set the current configuration

Usage: dsc.exe config set [OPTIONS]

Options:
  -i, --input <INPUT>                  The input document as JSON or YAML to pass to the configuration or resource
  -f, --file <FILE>                    The path to a file used as input to the configuration or resource. Use '-' for the file to read from STDIN.
  -o, --output-format <OUTPUT_FORMAT>  The output format to use [possible values: json, pretty-json, yaml]
  -w, --what-if                        Run as a what-if operation instead of executing the configuration or resource
  -h, --help                           Print help

then

PS> dsc config -h
Apply a configuration document

Usage: dsc.exe config [OPTIONS] <COMMAND>

Commands:
  get     Retrieve the current configuration
  set     Set the current configuration
  test    Test the current configuration
  export  Export the current configuration
  help    Print this message or the help of the given subcommand(s)

Options:
  -p, --parameters <PARAMETERS>
          Parameters to pass to the configuration as JSON or YAML
  -f, --parameters-file <PARAMETERS_FILE>
          Parameters to pass to the configuration as a JSON or YAML file
  -r, --system-root <SYSTEM_ROOT>
          Specify the operating system root path if not targeting the current running OS
  -h, --help
          Print help

and

PS> dsc -h
Apply configuration or invoke specific DSC resources

Usage: dsc.exe [OPTIONS] <COMMAND>

Commands:
  completer  Generate a shell completion script
  config     Apply a configuration document
  resource   Invoke a specific DSC resource
  schema     Get the JSON schema for a DSC type
  help       Print this message or the help of the given subcommand(s)

Options:
  -l, --trace-level <TRACE_LEVEL>
          Trace level to use [possible values: error, warn, info, debug, trace]
  -t, --trace-format <TRACE_FORMAT>
          Trace format to use [possible values: default, plaintext, json]
  -p, --progress-format <PROGRESS_FORMAT>
          Progress format to use [possible values: default, json]
  -h, --help
          Print help
  -V, --version
          Print version

Proposed technical implementation details (optional)

At a minimum, I would be nice for help to at least mention that the parent commands have their own options. And it would subtly inform you about the requirement for those options to be placed between the parent and child commands. Maybe like:

PS> dsc config set -h
Set the current configuration

Usage: dsc.exe [dsc.exe OPTIONS] config [config OPTIONS] set [OPTIONS]

Options:
  -i, --input <INPUT>                  The input document as JSON or YAML to pass to the configuration or resource
  -f, --file <FILE>                    The path to a file used as input to the configuration or resource. Use '-' for the file to read from STDIN.
  -o, --output-format <OUTPUT_FORMAT>  The output format to use [possible values: json, pretty-json, yaml]
  -w, --what-if                        Run as a what-if operation instead of executing the configuration or resource
  -h, --help                           Print help

For config command options, run `dsc.exe config --help`.
For dsc.exe options, run `dsc.exe --help`.

But to prevent needing to run those other commands, the "For ..., run ..." would need to be replaced with blocks of the options. This might be considered too much output, so it could be contained to the 2-3 top options with a "run for more" line. My example output already removes some of the options (like help) that don't need to be repeated/inherited.

PS> dsc config set -h
Set the current configuration

Usage: dsc.exe [dsc.exe OPTIONS] config [config OPTIONS] set [OPTIONS]

Options:
  -i, --input <INPUT>                  The input document as JSON or YAML to pass to the configuration or resource
  -f, --file <FILE>                    The path to a file used as input to the configuration or resource. Use '-' for the file to read from STDIN.
  -o, --output-format <OUTPUT_FORMAT>  The output format to use [possible values: json, pretty-json, yaml]
  -w, --what-if                        Run as a what-if operation instead of executing the configuration or resource
  -h, --help                           Print help

config Options:
  -p, --parameters <PARAMETERS>
          Parameters to pass to the configuration as JSON or YAML
  -f, --parameters-file <PARAMETERS_FILE>
          Parameters to pass to the configuration as a JSON or YAML file
  -r, --system-root <SYSTEM_ROOT>
          Specify the operating system root path if not targeting the current running OS

dsc.exe Options:
  -l, --trace-level <TRACE_LEVEL>
          Trace level to use [possible values: error, warn, info, debug, trace]
  -t, --trace-format <TRACE_FORMAT>
          Trace format to use [possible values: default, plaintext, json]
  -p, --progress-format <PROGRESS_FORMAT>
          Progress format to use [possible values: default, json]

[SteveL-MSFT]

The help is generated by the clap crate that we use. I think we could perhaps cover this in our official documentation particularly about context specific parameters and the tree nature of the sub-commands. cc @michaeltlombardi

[michaeltlombardi]

One of the things I want to try to address in the post 3.0 timeframe is fully review/extend the CLI help. We currently have a limited usage of the help subsystem in clap (primarily the short about help), but we could use the various help-related attributes to improve the CLI docs, particularly with the use of [help templates]¹.

While it isn't super-obvious how to do so, we can use a lot of the builder API functions as attributes in the derive API - which would also let us do things like flatten the subcommand help for the resource and config commands.

We can write some reusable i18n snippets (or make the help templates themselves subject to i18n) to include in subcommands so users don't have to back up the command-chain to review parent command operations.

I'm doing a review of the online v3 docs right now and will work to address these concerns there for now. The changes to the interactive help are a bit more involved and require some careful thinking/design that shouldn't make the 3.0 GA slip, in my opinion.
 

Footnotes

1. https://docs.rs/clap/latest/clap/struct.Command.html#method.help_template ↩