docs: improve command usage documentation

This PR makes command usage documentation consistent by enforcing [docopt](http://docopt.org/) rules and also defining and documenting other additional conventions.

Author: phm07

CONTRIBUTING.md

@@ -50,7 +50,7 @@ var ListCmd = base.Cmd{
 		}
 
 		cmd := &cobra.Command{
-			Use:   "list FLAGS",
+			Use:   "list [options]",
 			Short: "List all resources in the project",
 			Long: `List all resources in the project. This does not include static/public resources like locations, public ISOs, etc.
 

internal/cmd/all/list.go

@@ -26,8 +26,13 @@ type DeleteCmd struct {
 
 // CobraCommand creates a command that can be registered with cobra.
 func (dc *DeleteCmd) CobraCommand(s state.State) *cobra.Command {
+	opts := ""
+	if dc.AdditionalFlags != nil {
+		opts = "[options] "
+	}
+
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("delete [FLAGS] %s", strings.ToUpper(dc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("delete %s<%s>", opts, strings.ToLower(dc.ResourceNameSingular)),
 		Short:                 dc.ShortDescription,
 		Args:                  cobra.ExactArgs(1),
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(dc.NameSuggestions(s.Client()))),

internal/cmd/base/delete.go

@@ -33,7 +33,7 @@ type DescribeCmd struct {
 // CobraCommand creates a command that can be registered with cobra.
 func (dc *DescribeCmd) CobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("describe [FLAGS] %s", strings.ToUpper(dc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("describe [options] <%s>", strings.ToLower(dc.ResourceNameSingular)),
 		Short:                 dc.ShortDescription,
 		Args:                  cobra.ExactArgs(1),
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(dc.NameSuggestions(s.Client()))),

internal/cmd/base/describe.go

@@ -27,7 +27,7 @@ type LabelCmds struct {
 // AddCobraCommand creates a command that can be registered with cobra.
 func (lc *LabelCmds) AddCobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("add-label [FLAGS] %s LABEL...", strings.ToUpper(lc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("add-label [--overwrite] <%s> <label>...", strings.ToLower(lc.ResourceNameSingular)),
 		Short:                 lc.ShortDescriptionAdd,
 		Args:                  cobra.MinimumNArgs(2),
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(lc.NameSuggestions(s.Client()))),
@@ -89,7 +89,7 @@ func validateAddLabel(_ *cobra.Command, args []string) error {
 // RemoveCobraCommand creates a command that can be registered with cobra.
 func (lc *LabelCmds) RemoveCobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("remove-label [FLAGS] %s LABEL...", strings.ToUpper(lc.ResourceNameSingular)),
+		Use:   fmt.Sprintf("remove-label <%s> (--all | <label>...)", strings.ToLower(lc.ResourceNameSingular)),
 		Short: lc.ShortDescriptionRemove,
 		Args:  cobra.MinimumNArgs(1),
 		ValidArgsFunction: cmpl.SuggestArgs(

internal/cmd/base/labels.go

@@ -29,7 +29,7 @@ func (lc *ListCmd) CobraCommand(s state.State) *cobra.Command {
 	outputColumns := lc.OutputTable(s.Client()).Columns()
 
 	cmd := &cobra.Command{
-		Use:   "list [FlAGS]",
+		Use:   "list [options]",
 		Short: fmt.Sprintf("List %s", lc.ResourceNamePlural),
 		Long: util.ListLongDescription(
 			fmt.Sprintf("Displays a list of %s.", lc.ResourceNamePlural),

internal/cmd/base/list.go

@@ -28,7 +28,7 @@ type SetRdnsCmd struct {
 // CobraCommand creates a command that can be registered with cobra.
 func (rc *SetRdnsCmd) CobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("set-rdns [FLAGS] %s", strings.ToUpper(rc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("set-rdns [options] <%s> --hostname <hostname>", strings.ToLower(rc.ResourceNameSingular)),
 		Short:                 rc.ShortDescription,
 		Args:                  cobra.ExactArgs(1),
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(rc.NameSuggestions(s.Client()))),

internal/cmd/base/set_rdns.go

@@ -28,7 +28,7 @@ type UpdateCmd struct {
 // CobraCommand creates a command that can be registered with cobra.
 func (uc *UpdateCmd) CobraCommand(s state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:                   fmt.Sprintf("update [FLAGS] %s", strings.ToUpper(uc.ResourceNameSingular)),
+		Use:                   fmt.Sprintf("update [options] <%s>", strings.ToLower(uc.ResourceNameSingular)),
 		Short:                 uc.ShortDescription,
 		Args:                  cobra.ExactArgs(1),
 		ValidArgsFunction:     cmpl.SuggestArgs(cmpl.SuggestCandidatesF(uc.NameSuggestions(s.Client()))),

internal/cmd/base/update.go

@@ -17,7 +17,7 @@ import (
 var CreateCmd = base.CreateCmd{
 	BaseCobraCommand: func(client hcapi2.Client) *cobra.Command {
 		cmd := &cobra.Command{
-			Use:   "create [FLAGS]",
+			Use:   "create [options] --name <name> (--type managed | --type uploaded --cert-file <file> --key-file <file>)",
 			Short: "Create or upload a Certificate",
 			Args:  cobra.ExactArgs(0),
 		}

internal/cmd/certificate/create.go

@@ -33,7 +33,7 @@ import (
 
 func NewCommand(_ state.State) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "completion [FLAGS] SHELL",
+		Use:   "completion <shell>",
 		Short: "Output shell completion code for the specified shell",
 		Long: `To load completions: