Merge branch 'v3' into fix-model-status-owner

.github/workflows/publish-docs.yaml

@@ -0,0 +1,63 @@
+name: Publish Docs
+
+# This workflow builds jimmctl and generates a markdown formatted
+# documentation reference before converting the doc to rst and 
+# making a PR to the jaas-documentation repo to update the docs.
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v3*'
+
+jobs:
+  publish-jimmctl-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        fetch-tags: true
+    - run: git fetch --tags --force origin # https://github.com/actions/checkout/issues/882 & https://github.com/actions/checkout/issues/290 
+
+    - name: Build jimmctl
+      run: go build ./cmd/jimmctl/
+
+      # Default doc name is documentation.md which can't be changed via flags.
+    - name: Generate docs
+      run: ./jimmctl documentation --out .
+
+    - name: Convert doc to reStructuredText
+      uses: docker://pandoc/core:3.5
+      with:
+        args: "documentation.md -o documentation.rst --wrap=none"
+
+      # We do this because the original doc doesn't have a top level heading.: 
+    - name: Create final doc with title
+      run: |
+        echo "Jimmctl Reference" > jimmctl-reference.rst
+        echo "#################" >> jimmctl-reference.rst
+        echo "" >> jimmctl-reference.rst
+        cat documentation.rst >> jimmctl-reference.rst
+    
+    - name: Checkout docs
+      uses: actions/checkout@v4
+      with:
+        repository: 'canonical/jaas-documentation'
+        ref: 'v3'
+        path: ./jaas-documentation
+
+    - name: Update Docs
+      working-directory: ./jaas-documentation
+      run: cp ../jimmctl-reference.rst ./reference/jimmctl.rst
+
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@v6
+      with:
+        token: ${{ secrets.JIMM_GO_SDK_PAT }}
+        path: ./jaas-documentation
+        branch: update-jimmctl-${{ github.run_number }}
+        title: Update jimmctl reference doc
+        body: This PR updates the jimmctl reference doc.
+        commit-message: Updated jimmctl reference for release ${{ github.event.ref }}

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 user access management.
 `
 
 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,17 +58,19 @@ 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,
 	})
 }
 
 // SetFlags implements Command.SetFlags.
 func (c *controllerInfoCommand) SetFlags(f *gnuflag.FlagSet) {
 	c.CommandBase.SetFlags(f)
 	f.BoolVar(&c.local, "local", false, "If local flag is specified, then the local API address and CA cert of the controller will be used.")
-	f.StringVar(&c.tlsHostname, "tls-hostname", "", "Specify the hostname for TLS verfiication.")
+	f.StringVar(&c.tlsHostname, "tls-hostname", "", "Specify the hostname for TLS verification.")
 }
 
 // Init implements the cmd.Command interface.

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,
 	})
 }