Reorder and clean create help output

[hickeng]

At the moment there's a plethora of options to create, many of which are not needed for simple deployments.

We have an advanced help, however there's then little to no consistency in the ordering or argument and definitely none of the standard UX style mechanisms that make reading comprehension easier such as grouping of related flags and breaks between groups.

If we consider the normal help output to be as much a high level index as anything else and make the existence of advanced help much more explicit, then we can likely make this significantly more user friendly.

I've commented on urfave/cli#259 - we may have to create a PR for this as our args are getting incomprehensible.

Working example - concise:

# vic-machine-linux create --help
NAME:
   vic-machine-linux create - Deploy VCH

USAGE:
   vic-machine-linux create [command options] [arguments...]

OPTIONS:
   --target value, -t value                REQUIRED. ESXi or vCenter connection URL, specifying a datacenter if multiple exist e.g. root:password@VC-FQDN/datacenter (default: <nil>)
   --user value, -u value                  ESX or vCenter user
   --password value, -p value              ESX or vCenter password (default: <nil>)
   --compute-resource value, -r value      Compute resource path, e.g. myCluster/Resources/myRP. Default to <default cluster>/Resources
   --name value, -n value                  The name of the Virtual Container Host (default: "virtual-container-host")
   --image-store value, -i value           Image datastore path in format "datastore/path"
   --volume-store value, --vs value        Specify location and label for volume store; path optional: "datastore/path:label" or "datastore:label"
   --bridge-network value, -b value        The bridge network port group name (private port group for containers). Defaults to the Virtual Container Host name
   --client-network value, --cln value     The client network port group name (restricts DOCKER_API access to this network). Defaults to DCHP - see advanced help (-x)
   --external-network value, --en value    The external network port group name (port forwarding and default route). Defaults to 'VM Network' and DHCP -- see advanced help (-x)
   --management-network value, --mn value  The management network port group name (provides route to target hosting vSphere). Defaults to DCHP - see advanced help (-x)
   --container-network value, --cn value   vSphere networks that containers can use directly, without port forwarding. Defaults to DCHP - see advanced help (-x)
   --memory value, --mem value             VCH resource pool memory limit in MB (default: 0)
   --cpu value                             VCH resource pool vCPUs limit in MHz (default: 0)
   --tls-cname value                       Common Name to use in generated CA certificate when requiring client certificate authentication
   --no-tlsverify, --kv                    Disable authentication via client certificates - for more tls options see advanced help (-x)
   --insecure-registry value, --dir value  Specify a list of permitted insecure registry server URLs
   --appliance-iso value, --ai value       The appliance iso
   --bootstrap-iso value, --bi value       The bootstrap iso
   --force, -f                             Force the install, removing existing if present
   --timeout value                         Time to wait for create (default: 3m0s)
   --debug value, -v value                 [0(default),1...n], 0 is disabled, 1 is enabled, >= 1 may alter behaviour (default: 0)
   --advanced-options, -x                  Show all options - this must be specified instead of --help

Advanced

# vic-machine-linux create -x
NAME:
   vic-machine-linux create - Deploy VCH

USAGE:
   vic-machine-linux create [command options] [arguments...]

OPTIONS:
   --target value, -t value                         REQUIRED. ESXi or vCenter connection URL, specifying a datacenter if multiple exist e.g. root:password@VC-FQDN/datacenter (default: <nil>)
   --user value, -u value                           ESX or vCenter user
   --password value, -p value                       ESX or vCenter password (default: <nil>)
   --compute-resource value, -r value               Compute resource path, e.g. myCluster/Resources/myRP. Default to <default cluster>/Resources
   --name value, -n value                           The name of the Virtual Container Host (default: "virtual-container-host")
   --image-store value, -i value                    Image datastore path in format "datastore/path"
   --base-image-size value                          Specify the size of the base image from which all other images are created e.g. 8GB/8000MB (default: "8GB")
   --container-store value, --cs value              Container datastore path - not supported yet, defaults to image datastore
   --volume-store value, --vs value                 Specify location and label for volume store; path optional: "datastore/path:label" or "datastore:label"
   --bridge-network value, -b value                 The bridge network port group name (private port group for containers). Defaults to the Virtual Container Host name
   --bridge-network-range value, --bnr value        The IP range from which bridge networks are allocated (default: "172.16.0.0/12")
   --client-network value, --cln value              The client network port group name (restricts DOCKER_API access to this network). Defaults to DCHP - see advanced help (-x)
   --client-network-gateway value                   Gateway for the VCH on the client network, e.g. 10.0.0.1/24
   --client-network-ip value                        IP address for the VCH on the client network, e.g. 10.0.0.2/24
   --external-network value, --en value             The external network port group name (port forwarding and default route). Defaults to 'VM Network' and DHCP -- see advanced help (-x)
   --external-network-gateway value                 Gateway for the VCH on the external network, e.g. 10.0.1.1/24
   --external-network-ip value                      IP address for the VCH on the external network, e.g. 10.0.1.2/24
   --management-network value, --mn value           The management network port group name (provides route to target hosting vSphere). Defaults to DCHP - see advanced help (-x)
   --management-network-gateway value               Gateway for the VCH on the management network, e.g. 10.0.2.1/24
   --management-network-ip value                    IP address for the VCH on the management network, e.g. 10.0.2.2/24
   --dns-server value                               DNS server for the client, external, and management networks. Defaults to 8.8.8.8 and 8.8.4.4 when not using DHCP
   --container-network value, --cn value            vSphere networks that containers can use directly, without port forwarding. Defaults to DCHP - see advanced help (-x)
   --container-network-gateway value, --cng value   Gateway for the container network's subnet in CONTAINER-NETWORK:SUBNET format, e.g. a_network:172.16.0.0/16
   --container-network-ip-range value, --cnr value  IP range for the container network in CONTAINER-NETWORK:IP-RANGE format, e.g. a_network:172.16.0.0/24, a_network:172.16.0.10-20
   --container-network-dns value, --cnd value       DNS servers for the container network in CONTAINER-NETWORK:DNS format, e.g. a_network:8.8.8.8. Ignored if no static IP assigned.
   --memory value, --mem value                      VCH resource pool memory limit in MB (default: 0)
   --memory-reservation value, --memr value         VCH resource pool memory reservation in MB (default: 0)
   --memory-shares value, --mems value              VCH resource pool memory shares in level or share number, e.g. high, normal, low, or 163840 (default: <nil>)
   --appliance-memory value                         Memory for the appliance VM, in MB. Does not impact resources allocated per container. (default: 2048)
   --cpu value                                      VCH resource pool vCPUs limit in MHz (default: 0)
   --cpu-reservation value, --cpur value            VCH resource pool reservation in MHz (default: 0)
   --cpu-shares value, --cpus value                 VCH VCH resource pool vCPUs shares, in level or share number, e.g. high, normal, low, or 4000 (default: <nil>)
   --appliance-cpu value                            vCPUs for the appliance VM (default: 1)
   --tls-cname value                                Common Name to use in generated CA certificate when requiring client certificate authentication
   --organisation value                             Organisation to use for generated CA certificate (default: "default")
   --no-tlsverify, --kv                             Disable authentication via client certificates - for more tls options see advanced help (-x)
   --no-tls, -k                                     Disable TLS support completely
   --key value                                      Virtual Container Host private key file
   --cert value                                     Virtual Container Host x509 certificate file
   --tls-ca value, --ca value                       Specify a list of certificate authorities to use for client verification
   --certificate-key-size value, --ksz value        Size of key to use when generating certificates (default: 2048)
   --insecure-registry value, --dir value           Specify a list of permitted insecure registry server URLs
   --appliance-iso value, --ai value                The appliance iso
   --bootstrap-iso value, --bi value                The bootstrap iso
   --use-rp                                         Use resource pool for vch parent in VC instead of a vApp
   --force, -f                                      Force the install, removing existing if present
   --timeout value                                  Time to wait for create (default: 3m0s)
   --debug value, -v value                          [0(default),1...n], 0 is disabled, 1 is enabled, >= 1 may alter behaviour (default: 0)
   --advanced-options, -x                           Show all options - this must be specified instead of --help
   --help, -h                                       show help
   --generate-bash-completion

[hickeng]

I propose we do this asap - the examples above are from working code.

@mreferre @cormachogan what do you think of the revise output above?

[mreferre]

--advanced-options doesn't naturally convey (IMO) that it's a flag to SHOW extended help. In my head it means more like you are passing extended options to a command . Why not calling it --extended-help (-xh or even keeping -x for short)?

Also, in the "basic help" it would be nice to see an example of such command perhaps using the same syntax we are currently using in the alpha / beta workflows. e.g. :

./vic-machine-linux create --name <name> --target <address of vCenter or ESX> --user <vCenter/ESX uid> --password <pwd> --compute-resource <cluster/optional resource pool> --external-network <external network name> --bridge-network <bridge network name> --image-store <datastore name>

Ideally it should be the bare minimum to get a default VCH deployed.

Having something like this for extended options it would be too much as it would require a too long example for it to be meaningful but for standard help it may be a good way to start "shaping" a proper basic command that then the user can build upon.

[hickeng]

@mreferre thanks!

@emlin @andrewtchin I don't think we can express example commands using urfav/cli at the moment. Do you know if the template mechanism allows for such?

[emlin]

So you mean to derive example commands from command flags? I don't think there is such functions.
We'll have to write sample as a hardcoded doc in the command usage.

[hickeng]

@emlin As a follow up there is a Description field which can be added to the subcommand structure. It doesn't handle newlines, but you can sort of finesse it with \n\t\t, at least on linux.

I think it'll definitely be worth us creating a PR for urfave/cli that parses the various description strings for newlines and tabs and applies suitable indentation.