Inconsistent linebreaks in examples

[zikalino]

az feedback auto-generates most of the information requested below, as of CLI version 2.0.62

Describe the bug I was just checking examples for VM, and seems like linebreaks are not consistent, for instance:

In first case example is broken into lines manually in _help.py file:

    Create a Debian VM using Key Vault secrets.
        az keyvault certificate create --vault-name vaultname -n cert1 \
          -p "$(az keyvault certificate get-default-policy)"

        secrets=$(az keyvault secret list-versions --vault-name vaultname \
          -n cert1 --query "[?attributes.enabled].id" -o tsv)

        vm_secrets=$(az vm secret format -s "$secrets")

        az vm create -g group-name -n vm-name --admin-username deploy  \
          --image debian --secrets "$vm_secrets"

In second case example is included in a single unbroken line in _help.py and broken later into separate lines:

    Create a CentOS VM with a system assigned identity. The VM will have a 'Contributor' role with
    access to a storage account.
        az vm create -n MyVm -g rg1 --image centos --assign-identity --scope
        /subscriptions/99999999-1bf0-4dda-
        aec3-cb9272f09590/MyResourceGroup/myRG/providers/Microsoft.Storage/storageAccounts/storage1

To Reproduce

az vm create --help

Expected behavior We should have consistent way for linebreaks in examples

Environment summary Just used Windows commandline

Additional context

[adewaleo]

For the second example, the line should be broken. However sometimes we do have situations where full resource ids are specified, which should technically not be broken up.

Not sure what the solution would be regarding long resource IDs. But there should be a line break if a command is too long...

If we come up with a consensus on how long example commands should be broken up, we can add a linter rule to encourage or ensure the desired behavior.

[zikalino]

@adewaleo I think actually I have an idea how it should work. I think we shouldn't include line breaks (" ") in examples at all, and Azure CLI should format the example depending on the environment later. For instance "" doesn't work on windows, also breaking long string arguments causes problems (these line breaks will be passed)

[adewaleo]

Processing based on platform instead of in code makes sense.

However, I wonder if this could hurt readability / writability of very long examples. E.g. a command that takes multiple ids, could be many characters long, at least breaking along the parameter / option level can be helpful

[yonzhan]

add to S164.

[qwordy]

Can we remove the "\"? And let console auto-wrap lines.

[ghost]

Hi, we're sending this friendly reminder because we haven't heard back from you in a while. We need more information about this issue to help address it. Please be sure to give us your input within the next 7 days. If we don't hear back from you within 14 days of this comment the issue will be automatically closed. Thank you!