[Quantum] Show required parameters in CLI Reference documentation

[warren-jones]

Currently, almost all quantum CLI command parameters in the az quantum CLI reference documentation appear under “Optional Parameters”, which gives the impression that none of these parameters are required parameters. This has been criticized as confusing and misleading.

The az quantum CLI Reference documentation is automatically generated from source files like _params.py, _help.py, and the command function signatures, so it is not directly editable like our tutorials and how-to guides. The source code dictates which parameters are documented as required, and which parameters are optional.

A positive side effect of making these code changes is a dramatic improvement in the detail level of error messages about missing parameters, since we're leveraging the framework's error message generation feature that adds help examples.

The required vs. optional treatment of --location and --resource-group is not consistent throughout the Azure CLI, but for example, Azure Virtual Machines generally treats --resource-group as a required parameter, see https://docs.microsoft.com/en-us/cli/azure/vm/aem?view=azure-cli-latest

I believe the least user confusion will arise from designating them Required Parameters to leverage the CLI framework’s validation and detailed error message generation. For --location, the help text always includes You can configure the default location using az configure --defaults location=<location> and a similar note appears for --resource-group.

---

This checklist is used to make sure that common guidelines for a pull request are followed.

Related command

All az quantum commands

General Guidelines

• Have you run azdev style <YOUR_EXT> locally? (pip install azdev required)
• Have you run python scripts/ci/test_index.py -q locally?

[yonzhan]

Quantum

[warren-jones]

/azp run

[azure-pipelines]

Commenter does not have sufficient privileges for PR 5130 in repo Azure/azure-cli-extensions

[ricardo-espinoza]

Overall looks good to me, but we need to verify that the expectations from users when setting a default workspace (and its resource group) have not changed. Many of the commands were written with the idea that users would not need to specify -w/-g/-l if they already did an azure quantum workspace set, just in the same way that a target could also be set.

If usage has changed as a result of this PR, we need to discuss it in more detail.

[warren-jones]

@ricardo-espinoza,
I responded to your "Overall looks good to me, but we need to verify that the expectations from users..." comment in email, but I'll reiterate it here to keep the conversation together:

az quantum workspace set has the same effect as before -- so I think we’re OK. The difference is internal: Workspace name is saved in the [defaults] section of the .azure/config file instead or [quantum], along with group and location. Do you see a problem there?

[ricardo-espinoza]

Approved, but I hope that by the next release (after this one) the commented code is fixed.

[kairu-ms]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).