[Help] Help Fixes and Enhancements

[Travis Prescott (tjprescott)]

This PR fixes #365, fixes #447 and fixes #680. The first sentence of the docstring will be parsed as the short description and any subsequent sentences will be parsed as the long description. This largely takes care of issue #707 (although it doesn't address how adequate the reflected help is). Of course, you can override any of this through the YAML help file.

Additionally, this PR fixes an issue where choice lists would appear in random order in help.

[Travis Prescott (tjprescott)]

As an example for az vm -h

Group
    az vm

Subgroups:
    ...

Commands:
    capture               : Captures the VM by copying virtual hard disks of the VM and outputs a
                            template that can be used to create similar VMs.
    create                : Create an Azure Virtual Machine.
    deallocate            : Shuts down the Virtual Machine and releases the compute resources.
    delete                : The operation to delete a virtual machine.
    generalize            : Sets the state of the VM as Generalized.
    get-instance-view
    list                  : List Virtual Machines.
    list-ip-addresses     : Get IP addresses from one or more Virtual Machines.
    list-sizes            : Lists all available virtual machine sizes for a subscription in a
                            location.
    list-usage            : Lists compute usages for a subscription.
    list-vm-resize-options: Lists all available virtual machine sizes it can be resized to for a
                            virtual machine.
    open-port             : Opens a VM to all inbound traffic and protocols by adding a security
                            rule to the network security group (NSG) that is attached to the VM's
                            network interface (NIC) or subnet.
    redeploy              : The operation to redeploy a virtual machine.
    resize                : Update vm size.
    restart               : The operation to restart a virtual machine.
    show                  : The operation to get a virtual machine.
    start                 : The operation to start a virtual machine.
    stop                  : The operation to power off (stop) a virtual machine.
    update                : Update VM properties.
``` #ByDesign

[Johan Stenberg (ex-msft) (johanste)]

We should not compile a regex for each command we register. Performance.

[Burt Bielicki (BurtBiel)]

the regex can be pulled out of the method and compiled, then using the precompiled version will be faster

---

In reply to: 75970919 [](ancestors = 75970919)

[Travis Prescott (tjprescott)]

Command

Also, I will get getting rid of this file before I merge. I used it to diff and make sure my changes for fixing the issue with : didn't break other things. #Resolved

---

Refers to: help_dump.txt:2 in 0d7d269. [](commit_id = 0d7d26977e1a5d6f36d5aea5cdcd3034e03f5504, deletion_comment = False)

[Burt Bielicki (BurtBiel)]

                  max_name_length + indent*4 + 2)

let's factor this and the version in your code out into a helper method like _get_hanging_indent. We might as well add a comment in that method or a constant for why we do the +2 (for the colon + space) #Resolved

---

Refers to: src/azure/cli/_help.py:106 in 0d7d269. [](commit_id = 0d7d26977e1a5d6f36d5aea5cdcd3034e03f5504, deletion_comment = False)

[Burt Bielicki (BurtBiel)]

self.long_summary = None [](start = 12, length = 24)

technically don't need this #Resolved

[Travis Prescott (tjprescott)]

Good point. I had it the other way around originally but that caused the help tests to fail, so I changed it to conform to the tests. Unit test win.

---

In reply to: 76083810 [](ancestors = 76083810)

[Travis Prescott (tjprescott)]

Johan Stenberg (ex-msft) (@johanste) Burt Bielicki (@BurtBiel) comments addressed. #Closed

[Burt Bielicki (BurtBiel)]

nit: this could be moved next to get column indent since they are closely related #Resolved

[Travis Prescott (tjprescott)]

Burt Bielicki (@BurtBiel) comments addressed. #Closed