fix(doc): short as command and fix some worker command description (#…

…3341) Signed-off-by: Yvonnick Esnault <yvonnick.esnault@corp.ovh.com>
ovh · Sep 20, 2018 · f8b1e57 · f8b1e57
1 parent cee0195
commit f8b1e57
Show file tree

Hide file tree

Showing 9 changed files with 31 additions and 18 deletions.
diff --git a/engine/worker/cmd_cache.go b/engine/worker/cmd_cache.go
@@ -59,9 +59,7 @@ Here, an example of a script inside a CDS Job using the cache feature:
 	# put in cache the updated .m2/ directory
 	worker cache push $tag .m2/
 
-
     `,
-		Short: "Inside a project, you can create or retrieve a cache from your worker with a tag",
 	}
 	cmdCacheRoot.AddCommand(cmdCachePush(w), cmdCachePull(w))
 

diff --git a/engine/worker/cmd_download.go b/engine/worker/cmd_download.go
@@ -32,11 +32,18 @@ func cmdDownload(w *currentWorker) *cobra.Command {
 Inside a job, there are two ways to download an artifact:
 
 * with a step using action Download Artifacts
-* with a step script (https://ovh.github.io/cds/workflows/pipelines/actions/builtin/script/), using the worker command: ` + "`worker download --tag=<tag> <path>`" + `
+* with a step script (https://ovh.github.io/cds/workflows/pipelines/actions/builtin/script/), using the worker command.
+
+Worker Command:
+
+	worker download --tag=<tag> <path>
+
+Example:
 
 	worker download --pattern="files.*.yml"
 
-	#theses two commands have the same result:
+Theses two commands have the same result:
+
 	worker download
 	worker download --workflow={{.cds.workflow}} --number={{.cds.run.number}}
 

diff --git a/engine/worker/cmd_export.go b/engine/worker/cmd_export.go
@@ -24,7 +24,6 @@ var cmdExport = &cobra.Command{
 	Long: `
 Inside a step script (https://ovh.github.io/cds/workflows/pipelines/actions/builtin/script/), you can create a build variable with the worker command:
 
-	# worker export <varname> <value>
 	worker export foo bar
 
 

diff --git a/engine/worker/cmd_key.go b/engine/worker/cmd_key.go
@@ -28,11 +28,8 @@ type keyResponse struct {
 
 func cmdKey(w *currentWorker) *cobra.Command {
 	cmdKeyRoot := &cobra.Command{
-		Use: "key",
-		Long: `
-
-    `,
-		Short: "Inside a step script you can install/uninstall a ssh key generated in CDS in your ssh environment",
+		Use:  "key",
+		Long: "Inside a step script you can install/uninstall a ssh key generated in CDS in your ssh environment",
 	}
 	cmdKeyRoot.AddCommand(cmdKeyInstall(w))
 

diff --git a/engine/worker/cmd_register.go b/engine/worker/cmd_register.go
@@ -11,9 +11,10 @@ import (
 
 func cmdRegister(w *currentWorker) *cobra.Command {
 	var cmdRegister = &cobra.Command{
-		Use:   "register",
-		Short: "worker register",
-		Run:   cmdRegisterRun(w),
+		Use:    "register",
+		Long:   "worker register is a subcommand used by hatchery. This is not directly useful for end user",
+		Hidden: true, // user should not use this command directly
+		Run:    cmdRegisterRun(w),
 	}
 	initFlagsRun(cmdRegister)
 	return cmdRegister

diff --git a/engine/worker/cmd_run.go b/engine/worker/cmd_run.go
@@ -20,7 +20,6 @@ import (
 func cmdRun(w *currentWorker) *cobra.Command {
 	c := &cobra.Command{
 		Use:    "run",
-		Short:  "worker run.",
 		Hidden: true, // user should not use this command directly
 		Run:    runCmd(w),
 	}

diff --git a/engine/worker/cmd_update.go b/engine/worker/cmd_update.go
@@ -18,8 +18,18 @@ import (
 func cmdUpdate(w *currentWorker) *cobra.Command {
 	c := &cobra.Command{
 		Use:   "update",
-		Short: "Update worker from CDS API or from CDS Release",
-		Run:   updateCmd(w),
+		Short: "worker update [flags]",
+		Long: `Update worker from CDS API or from CDS Release
+
+Update from Github:
+
+		worker update --from-github
+
+Update from your CDS API:
+
+		worker update --api https://your-cds-api.localhost
+		`,
+		Run: updateCmd(w),
 	}
 	c.Flags().Bool(flagFromGithub, false, "Update binary from latest github release")
 	c.Flags().String(flagAPI, "", "URL of CDS API")

diff --git a/engine/worker/cmd_upload.go b/engine/worker/cmd_upload.go
@@ -28,8 +28,7 @@ Inside a job, there are two ways to upload an artifact:
 * with a step using action Upload Artifacts
 * with a step script (https://ovh.github.io/cds/workflows/pipelines/actions/builtin/script/), using the worker command: ` + "`worker upload <path>`" + `
 
-	# worker upload --tag=<tag> <path>
-	worker upload --tag={{.cds.version}} {{.cds.workspace}}/files*.yml
+` + "`worker upload --tag={{.cds.version}} {{.cds.workspace}}/files*.yml`" + `
 
 		`,
 		Run: uploadCmd(w),

diff --git a/sdk/doc/generate.go b/sdk/doc/generate.go
@@ -82,6 +82,9 @@ func genMarkdownTreeCustom(cmd *cobra.Command, rootdir string, filePrepender, li
 		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
+		if c.Short != "" {
+			c.Short = fmt.Sprintf("`%s`", c.Short)
+		}
 		if err := genMarkdownTreeCustom(c, rootdir, filePrepender, linkHandler); err != nil {
 			return err
 		}