chore: update jimmctl command info

1. Populate the `Examples` field of all commands for correct documentation generation.
2. Changed examples that contained <controller> to an actual string like mycontroller. I copied Juju's help text e.g. `juju add-cloud -h` uses mycontroller and mycloud in their examples.
3. Populate the `Args` field of all commands for correct documentation generation.
4. Removed indentation from the command's doc string to match Juju's output.
5. Nested commands like auth should have the `UsagePrefix` field set.

cmd/jimmctl/cmd/addcloudtocontroller.go

@@ -25,18 +25,18 @@ import (
 	apiparams "github.com/canonical/jimm/v3/pkg/api/params"
 )
 
-var (
+const (
 	addCloudToControllerCommandDoc = `
-	add-cloud-to-controller command adds the specified cloud to a specific 
-	controller on jimm.
+The add-cloud-to-controller command adds the specified cloud to a specific 
+controller on jimm.
 
-	One can specify a cloud definition via a yaml file passed with the --cloud 
-	flag. If the flag is missing, the command will assume the cloud definition
-	is already known and will error otherwise.
-
-	Example:
-		jimmctl add-cloud-to-controller <controller_name> <cloud_name>
-		jimmctl add-cloud-to-controller <controller_name> <cloud_name> --cloud=<cloud_file_path> 
+One can specify a cloud definition via a yaml file passed with the --cloud 
+flag. If the flag is missing, the command will assume the cloud definition
+is already known and will error otherwise.
+`
+	addCloudToControllerExample = `
+    jimmctl add-cloud-to-controller mycontroller mycloud
+    jimmctl add-cloud-to-controller mycontroller mycloud --cloud=./cloud-definition.yaml
 `
 )
 
@@ -78,9 +78,11 @@ type addCloudToControllerCommand struct {
 // Info implements Command.Info.
 func (c *addCloudToControllerCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "add-cloud-to-controller",
-		Purpose: "Add cloud to specific controller in jimm",
-		Doc:     addCloudToControllerCommandDoc,
+		Name:     "add-cloud-to-controller",
+		Args:     "<controller_name> <cloud_name>",
+		Purpose:  "Add cloud to specific controller in jimm",
+		Doc:      addCloudToControllerCommandDoc,
+		Examples: addCloudToControllerExample,
 	})
 }
 

cmd/jimmctl/cmd/addcontroller.go

@@ -21,11 +21,11 @@ var (
 	stdinMarkers = []string{"-"}
 
 	addControllerCommandDoc = `
-	add-controller command adds a controller to jimm.
-
-	Example:
-		jimmctl add-controller <filename> 
-		jimmctl add-controller <filename> --format json
+The add-controller command adds a controller to jimm.
+`
+	addControllerCommandExample = `
+    jimmctl add-controller ./controller-info 
+    jimmctl add-controller ./controller-info.yaml --format json
 `
 )
 
@@ -50,9 +50,11 @@ type addControllerCommand struct {
 
 func (c *addControllerCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "add-controller",
-		Purpose: "Add controller to jimm",
-		Doc:     addControllerCommandDoc,
+		Name:     "add-controller",
+		Purpose:  "Add controller to jimm",
+		Args:     "<filepath>",
+		Doc:      addControllerCommandDoc,
+		Examples: addControllerCommandExample,
 	})
 }
 

cmd/jimmctl/cmd/auth.go

@@ -6,15 +6,16 @@ import (
 	jujucmd "github.com/juju/cmd/v3"
 )
 
-var authDoc = `
-auth enables users to manage authorisation model used by JIMM.
+const authDoc = `
+The auth command enables users to manage authorisation model used by JIMM.
 `
 
 func NewAuthCommand() *jujucmd.SuperCommand {
 	cmd := jujucmd.NewSuperCommand(jujucmd.SuperCommandParams{
-		Name:    "auth",
-		Doc:     authDoc,
-		Purpose: "Authorisation model management.",
+		Name:        "auth",
+		UsagePrefix: "jimmctl",
+		Doc:         authDoc,
+		Purpose:     "Authorisation model management.",
 	})
 	cmd.Register(NewGroupCommand())
 	cmd.Register(NewRelationCommand())

cmd/jimmctl/cmd/controllerinfo.go

@@ -16,22 +16,20 @@ import (
 	apiparams "github.com/canonical/jimm/v3/pkg/api/params"
 )
 
-var (
+const (
 	controllerInfoCommandDoc = `
-	controller-info command writes controller information contained
-	in the juju client store to a yaml file.
+The controller-info command writes controller information contained
+in the juju client store to a yaml file.
 
-	If a public address is specified, the output controller information
-	will contain the public address provided and omit a CA cert, this assumes
-	that the server is secured with a public certificate.
-	
-	Use the --local flag if the server is not configured with a public cert.
+If a public address is specified, the output controller information
+will contain the public address provided and omit a CA cert, this assumes
+that the server is secured with a public certificate.
 
-	See examples below for usage.
-
-	Examples:
-		jimmctl controller-info <name> <filename> <public address> 
-		jimmctl controller-info <name> <filename> --local
+Use the --local flag if the server is not configured with a public address.
+`
+	controllerInfoCommandExample = `
+    jimmctl controller-info mycontroller ./destination/file.yaml mycontroller.example.com 
+    jimmctl controller-info mycontroller ./destination/file.yaml --local
 `
 )
 
@@ -60,9 +58,11 @@ type controllerInfoCommand struct {
 
 func (c *controllerInfoCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "controller-info",
-		Purpose: "Stores controller info to a yaml file",
-		Doc:     controllerInfoCommandDoc,
+		Name:     "controller-info",
+		Args:     "<name> <filepath> [<public address>]",
+		Purpose:  "Stores controller info to a yaml file",
+		Doc:      controllerInfoCommandDoc,
+		Examples: controllerInfoCommandExample,
 	})
 }
 

cmd/jimmctl/cmd/crossmodelquery.go

@@ -15,20 +15,20 @@ import (
 	apiparams "github.com/canonical/jimm/v3/pkg/api/params"
 )
 
-var (
+const (
 	// stdinMarkers contains file names that are taken to be stdin.
 	crossModelQueryDoc = `
-query-models command queries all models available to the current user
+The query-models command queries all models available to the current user
 performing the query against each model status individually, returning
 the collated query responses for each model.
 
-The query will run against the exact output of "juju status --format json",
+The query runs against the output of "juju status --format json",
 as such you can format your query against an output like this.
 
-The queries will expect a JQ query string.
-
-Example:
-	jimmctl query-models '.applications | with_entries(select(.key=="nginx-ingress-integrator"))'
+The queries expect a JQ query string.
+`
+	crossModelQueryExample = `
+    jimmctl query-models '.applications | with_entries(select(.key=="nginx-ingress-integrator"))'
 `
 )
 
@@ -80,9 +80,11 @@ func (c *crossModelQueryCommand) SetFlags(f *gnuflag.FlagSet) {
 // Info implements modelcmd.Command.
 func (c *crossModelQueryCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "query-models",
-		Purpose: "Query model statuses",
-		Doc:     crossModelQueryDoc,
+		Name:     "query-models",
+		Args:     "<query>",
+		Purpose:  "Query model statuses",
+		Doc:      crossModelQueryDoc,
+		Examples: crossModelQueryExample,
 	})
 }
 

cmd/jimmctl/cmd/grantauditlogaccess.go

@@ -16,12 +16,15 @@ import (
 	apiparams "github.com/canonical/jimm/v3/pkg/api/params"
 )
 
-var grantAuditLogAccessDoc = `
-	grant-audit-log-access grants user access to audit logs.
+const (
+	grantAuditLogAccessDoc = `
+Grants a user access to read audit logs.
+`
 
-	Example:
-		jimmctl grant-audit-log-access <username> 
+	grantAuditLogAccessExamples = `
+    jimmctl grant-audit-log-access <username> 
 `
+)
 
 // NewGrantAuditLogAccessCommand returns a command used to grant
 // users access to audit logs.
@@ -45,9 +48,11 @@ type grantAuditLogAccessCommand struct {
 
 func (c *grantAuditLogAccessCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "grant-audit-log-access",
-		Purpose: "Grants access to audit logs.",
-		Doc:     grantAuditLogAccessDoc,
+		Name:     "grant-audit-log-access",
+		Args:     "<username>",
+		Purpose:  "Grants access to audit logs.",
+		Doc:      grantAuditLogAccessDoc,
+		Examples: grantAuditLogAccessExamples,
 	})
 }
 

cmd/jimmctl/cmd/group.go

@@ -20,47 +20,46 @@ import (
 	apiparams "github.com/canonical/jimm/v3/pkg/api/params"
 )
 
-var (
+const (
 	groupDoc = `
-group command enables group management for jimm
+The group command enables group management for jimm
 `
 
 	addGroupDoc = `
-add command adds group to jimm.
-
-Example:
-	jimmctl auth group add <name> 
+The add command adds group to jimm.
+`
+	addGroupExample = `
+    jimmctl auth group add mygroup
 `
 	renameGroupDoc = `
-rename command renames a group in jimm.
-
-Example:
-	jimmctl auth group rename <name> <new name>
+The rename command renames a group in jimm.
+`
+	renameGroupExample = `
+    jimmctl auth group rename mygroup newgroup
 `
 	removeGroupDoc = `
-rename command removes a group in jimm.
-
-Usage:
--y	Remove group without promping for confirmation
+The remove command removes a group in jimm.
+`
 
-Example:
-	jimmctl auth group remove <name>
+	removeGroupExample = `
+    jimmctl auth group remove mygroup
 `
 
 	listGroupsDoc = `
-list command lists all groups in jimm.
-
-Example:
-	jimmctl auth group list
+The list command lists all groups in jimm.
+`
+	listGroupsExample = `
+    jimmctl auth group list
 `
 )
 
 // NewGroupCommand returns a command for group management.
 func NewGroupCommand() *jujucmdv3.SuperCommand {
 	cmd := jujucmd.NewSuperCommand(jujucmdv3.SuperCommandParams{
-		Name:    "group",
-		Doc:     groupDoc,
-		Purpose: "Group management.",
+		Name:        "group",
+		UsagePrefix: "auth",
+		Doc:         groupDoc,
+		Purpose:     "Group management.",
 	})
 	cmd.Register(newAddGroupCommand())
 	cmd.Register(newRenameGroupCommand())
@@ -93,9 +92,11 @@ type addGroupCommand struct {
 // Info implements the cmd.Command interface.
 func (c *addGroupCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "add",
-		Purpose: "Add group to jimm.",
-		Doc:     addGroupDoc,
+		Name:     "add",
+		Args:     "<name>",
+		Purpose:  "Add group to jimm.",
+		Doc:      addGroupDoc,
+		Examples: addGroupExample,
 	})
 }
 
@@ -170,9 +171,11 @@ type renameGroupCommand struct {
 // Info implements the cmd.Command interface.
 func (c *renameGroupCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "rename",
-		Purpose: "Rename a group.",
-		Doc:     renameGroupDoc,
+		Name:     "rename",
+		Args:     "<name> <new name>",
+		Purpose:  "Rename a group.",
+		Doc:      renameGroupDoc,
+		Examples: renameGroupExample,
 	})
 }
 
@@ -238,9 +241,11 @@ type removeGroupCommand struct {
 // Info implements the cmd.Command interface.
 func (c *removeGroupCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "remove",
-		Purpose: "Remove a group.",
-		Doc:     removeGroupDoc,
+		Name:     "remove",
+		Args:     "<name>",
+		Purpose:  "Remove a group.",
+		Doc:      removeGroupDoc,
+		Examples: removeGroupExample,
 	})
 }
 
@@ -331,9 +336,10 @@ type listGroupsCommand struct {
 // Info implements the cmd.Command interface.
 func (c *listGroupsCommand) Info() *cmd.Info {
 	return jujucmd.Info(&cmd.Info{
-		Name:    "list",
-		Purpose: "List all groups.",
-		Doc:     listGroupsDoc,
+		Name:     "list",
+		Purpose:  "List all groups.",
+		Doc:      listGroupsDoc,
+		Examples: listGroupsExample,
 	})
 }