Merge pull request #874 from SoftLayer/issues873

Added a doc builder to buildAndDeploy, …

Author: allmightyspiff

README.md

@@ -467,6 +467,16 @@ ALSO:
 ## CLI Documentation
 To make changes to the cli documentation, do so here: https://github.ibm.com/cloud-docs/cli/tree/draft/reference/ibmcloud
 
+Docs for the `sl` plugin specifically live in this repo: https://github.ibm.com/cloud-docs/cli
+
+in `docs/` there is a utility that will generate the appropriate pages for the sl plugin.
+
+(assuming `~/Code/ibm-cloud-docs-cl` is where the cloud-docs have been checked out to.)
+```
+./bin/buildAndDeploy.py docs ~/Code/ibm-cloud-docs-cli
+ Building documentation builder:  go build -o docBuilder docs/main.go
+ Building documentation: ./docBuilder -o C:/Users/allmi/Code/ibm-cloud-docs-cli/_include-segments -v
+```
 
 # Code Patterns
 

bin/buildAndDeploy.py

@@ -321,6 +321,25 @@ def goBuild(self, theOs: str, theArch: str) -> None:
         # This command basically requires shell=True on mac because -ldflags doesn't get parsed properly withoutit.
         subprocess.run(buildCmd, shell=True)
 
+    def buildDocs(self, out_path: str) -> None:
+        """Generates the IBM Cloud CLI Documentation
+
+        :param str out_path: location of https://github.ibm.com/cloud-docs/cli repositry
+        """
+
+        # Step 1, build the builder:
+        buildCmd = f" go build -o docBuilder docs/main.go"
+        print(f"[turquoise2] Building documentation builder: {buildCmd}")
+        subprocess.run(buildCmd, shell=True)
+
+        # Check if out_dir is good:
+        if os.path.isdir(f"{out_path}/_include-segments") == False:
+            raise Exception(f"{out_path}/_include-segments does not exist, or not reachable from {self.cwd}")
+
+        docsCmd = f"./docBuilder -o {out_path}/_include-segments -v"
+        print(f"[turquoise2] Building documentation: {docsCmd}")
+        subprocess.run(docsCmd)
+
 @click.group()
 @click.pass_context
 def cli(ctx):
@@ -379,6 +398,17 @@ def i18n(ctx):
     runI18n4go(ctx.obj.getdir())
     # genBinData()
 
+@cli.command()
+@click.argument("out_path")
+@click.pass_context
+def docs(ctx, out_path):
+    """Generate the documentation files.
+
+    Requires a copy of https://github.ibm.com/cloud-docs/cli checked out.
+    out_path should point to the root directory of the cli repository.
+    """
+    ctx.obj.buildDocs(out_path)
+
 if __name__ == '__main__':
     cli()
     # try:

docs/main.go

@@ -16,6 +16,8 @@ import (
 )
 
 var fileName string
+var outputPath string
+var debug bool
 var rootCmd = &cobra.Command{
 	Use:   "doc-gen",
 	Short: "Generate the documentation for the sl plugin",
@@ -25,7 +27,10 @@ var rootCmd = &cobra.Command{
 	},
 }
 
+
 func main() {
+	rootCmd.Flags().StringVarP(&outputPath, "output", "o", "./docs", "Output path, default to ./docs .")
+	rootCmd.Flags().BoolVarP(&debug, "verbose", "v", false, "Enable Debug logging.")
 	err := rootCmd.Execute()
 	checkError(err)
 	return
@@ -84,6 +89,7 @@ func CliDocs() {
 			// This is a single command, like 'call-api' and doesn't have sub-commands
 			thisCmdGroup.Commands = []SlCmdDoc{cobraToSl(iCmd, "")}
 		}
+		printDebug(fmt.Sprintf("Working on command group %s\n", shortName))
 		PrintMakrdown(thisCmdGroup)
 		CmdGroups = append(CmdGroups, thisCmdGroup)
 	}
@@ -121,7 +127,8 @@ ibmcloud {{.Use}}
 
 	mdTemplate, err := template.New("cmd template").Parse(cmdTemplate)
 	checkError(err)
-	filename := fmt.Sprintf("%v.md", cmd.CommandShortLink)
+	filename := fmt.Sprintf("%s/%v.md", outputPath, cmd.CommandShortLink)
+	printDebug(fmt.Sprintf("\tCreating file %s\n", filename))
 	outfile, err := os.Create(filename) //#nosec G304 -- This is a false positive
 	defer outfile.Close()
 	err = mdTemplate.Execute(outfile, cmd)
@@ -201,3 +208,9 @@ func buildSlCmdFlag(topCommand *cobra.Command) []SlCmdFlag {
 	})
 	return flags
 }
+
+func printDebug(output string) {
+	if debug {
+		fmt.Printf(output)
+	}
+}

go.mod

@@ -10,7 +10,8 @@ require (
 	github.com/nicksnyder/go-i18n/v2 v2.4.0
 	github.com/onsi/ginkgo/v2 v2.17.1
 	github.com/onsi/gomega v1.33.0
-	github.com/softlayer/softlayer-go v1.1.5
+	github.com/sethvargo/go-password v0.3.1
+	github.com/softlayer/softlayer-go v1.1.6
 	github.com/spf13/cobra v1.8.1
 	github.com/spf13/pflag v1.0.5
 	github.com/stretchr/testify v1.9.0
@@ -34,7 +35,6 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/rogpeppe/go-internal v1.9.0 // indirect
-	github.com/sethvargo/go-password v0.3.1 // indirect
 	github.com/softlayer/xmlrpc v0.0.0-20200409220501-5f089df7cb7e // indirect
 	golang.org/x/crypto v0.24.0 // indirect
 	golang.org/x/mod v0.18.0 // indirect

go.sum

@@ -72,8 +72,8 @@ github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d h1:zE9ykE
 github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
 github.com/smartystreets/goconvey v1.6.7 h1:I6tZjLXD2Q1kjvNbIzB1wvQBsXmKXiVrhpRE8ZjP5jY=
 github.com/smartystreets/goconvey v1.6.7/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
-github.com/softlayer/softlayer-go v1.1.5 h1:UFFtgKxiw0yIuUw93XBCFIiIMYR5eLgmm4a5DqMHXGg=
-github.com/softlayer/softlayer-go v1.1.5/go.mod h1:WeJrBLoTJcaT8nO1azeyHyNpo/fDLtbpbvh+pzts+Qw=
+github.com/softlayer/softlayer-go v1.1.6 h1:VRNXiXZTpb7cfKjimU5E7W9zzKYzWMr/xtqlJ0pHwkQ=
+github.com/softlayer/softlayer-go v1.1.6/go.mod h1:WeJrBLoTJcaT8nO1azeyHyNpo/fDLtbpbvh+pzts+Qw=
 github.com/softlayer/xmlrpc v0.0.0-20200409220501-5f089df7cb7e h1:3OgWYFw7jxCZPcvAg+4R8A50GZ+CCkARF10lxu2qDsQ=
 github.com/softlayer/xmlrpc v0.0.0-20200409220501-5f089df7cb7e/go.mod h1:fKZCUVdirrxrBpwd9wb+lSoVixvpwAu8eHzbQB2tums=
 github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=

plugin/commands/user/list.go

@@ -1,7 +1,7 @@
 package user
 
 import (
-	"fmt"
+	"sort"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -51,12 +51,12 @@ func NewListCommand(sl *metadata.SoftlayerCommand) (cmd *ListCommand) {
 		},
 	}
 
-	columns := ""
+	columns := []string{}
 	for key, _ := range maskMap {
-		columns = fmt.Sprintf("%s %s,", columns, key)
+		columns = append(columns, key)
 	}
-	columns = strings.TrimSuffix(columns, ",")
-	subs := map[string]interface{}{"Columns": columns}
+	sort.Strings(columns)
+	subs := map[string]interface{}{"Columns": strings.Join(columns, ", ")}
 	cobraCmd.Flags().StringSliceVar(&thisCmd.Column, "column", []string{},
 		T("Column to display. options are: {{.Columns}}. This option can be specified multiple times", subs))