[Quantum] [DRAFT - Do not merge] 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 the parameters are required parameters. This has been called out as confusing or misleading.

The az quantum CLI Reference documentation is automatically generated from source files like _params.py, _help.py, and the command function signatures, hence it is not directly editable like our tutorials and how-to guides.

A positive side effect of making these code changes is a dramatic improvement in the verbosity of error messages about missing parameters.

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

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

[yonzhan]

Quantum

[warren-jones]

/azp run

[azure-pipelines[bot]]

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

[kairu-ms]

/azp run

[azure-pipelines[bot]]

Azure Pipelines successfully started running 1 pipeline(s).

[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?

[kairu-ms]

/azp run

[azure-pipelines[bot]]

Azure Pipelines successfully started running 1 pipeline(s).