overhaul help messages

mykso · Dec 17, 2024 · e54e5cc · e54e5cc
1 parent fe30e98
commit e54e5cc
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 66 deletions.
diff --git a/cmd/all.go b/cmd/all.go
@@ -8,30 +8,10 @@ import (
 )
 
 var allCmd = &cobra.Command{
-	Use:   "all [environments] [applications]",
-	Short: "Run sync and render for selected environments and applications",
-	Long: `Run sync and render for selected environments and applications
-
-Usage:
-  myks all [environments] [applications] [flags]
-
-Environments:
-  A comma-separated list of environments to render. If you provide "ALL", all environments will be rendered.
-
-Applications:
-  A comma-separated list of applications to render. If you don't provide this argument or provide "ALL", all applications will be rendered.
-
-Flags:
-  -h, --help   help for all
-
-Global Flags:
-  -a, --async int                         sets the number of applications to be processed in parallel
-                                          the default (0) is no limit
-      --config string                     config file (default is the first .myks.yaml up the directory tree)
-  -l, --log-level string                  set the logging level (default "info")
-      --smart-mode.base-revision string   base revision to compare against in Smart Mode
-                                          if not provided, only local changes will be considered
-      --smart-mode.only-print             only print the list of environments and applications that would be rendered in Smart Mode`,
+	Use:   "all",
+	Short: "Run sync and render",
+	Long:  "Run sync and render for specified environments and applications",
+	Args:  cobra.RangeArgs(0, 2),
 	Annotations: map[string]string{
 		ANNOTATION_SMART_MODE: ANNOTATION_TRUE,
 	},

diff --git a/cmd/render.go b/cmd/render.go
@@ -10,7 +10,7 @@ import (
 var renderCmd = &cobra.Command{
 	Use:   "render",
 	Short: "Render manifests",
-	Long:  "Render manifests",
+	Long:  "Render manifests for specified environments and applications",
 	Annotations: map[string]string{
 		ANNOTATION_SMART_MODE: ANNOTATION_TRUE,
 	},

diff --git a/cmd/root.go b/cmd/root.go
@@ -27,38 +27,97 @@ var (
 	asyncLevel int
 )
 
+// Use this template for commands that accept environment and application arguments
+const envAppCommandUsageTemplate = `Usage:
+  {{.CommandPath}} [environments [applications]] [flags]
+
+Arguments:
+  0. When no arguments are provided, myks uses the Smart Mode to determine the environments and applications to process.
+     In Smart Mode, myks relies on git to only processes applications with changes.
+
+  1. environments    (Optional) Comma-separated list of environments or ALL
+                     ALL will process all environments
+                     Examples: ALL
+                               prod,stage,dev
+                               prod/region1,stage/region1
+                               dev
+
+  2. applications    (Optional) Comma-separated list of applications or ALL
+                     ALL will process all applications
+                     Example: app1,app2 or ALL
+
+{{if .HasAvailableFlags}}Flags:
+{{.Flags.FlagUsages | trimTrailingWhitespaces}}{{end}}
+
+Examples:
+  # Process all apps in production and staging
+  {{.CommandPath}} prod,stage ALL
+
+  # Process specific apps in all environments
+  {{.CommandPath}} ALL app1,app2
+
+  # Process specific apps in specific environments
+  {{.CommandPath}} prod,stage app1,app2
+`
+
 func NewMyksCmd(version, commit, date string) *cobra.Command {
 	cobra.OnInitialize(initLogger)
 	zerolog.SetGlobalLevel(zerolog.InfoLevel)
 	cmd := newRootCmd(version, commit, date)
 	cmd.AddCommand(allCmd)
 	cmd.AddCommand(renderCmd)
+	cmd.AddCommand(syncCmd)
 	cmd.AddCommand(newCleanupCmd())
 	cmd.AddCommand(newInitCmd())
 	cmd.AddCommand(newPrintConfigCmd())
-	cmd.AddCommand(newSyncCmd())
 	cmd.AddCommand(embedded.EmbeddedCmd("vendir", "Vendir is embedded in myks to manage vendir.yaml files."))
 	cmd.AddCommand(embedded.EmbeddedCmd("ytt", "Ytt is embedded in myks to manage yaml files."))
 	initConfig()
 	addPlugins(cmd)
+
+	allCmd.SetUsageTemplate(envAppCommandUsageTemplate)
+	renderCmd.SetUsageTemplate(envAppCommandUsageTemplate)
+	syncCmd.SetUsageTemplate(envAppCommandUsageTemplate)
+
 	return cmd
 }
 
 func newRootCmd(version, commit, date string) *cobra.Command {
 	rootCmd := &cobra.Command{
 		Use:   "myks",
-		Short: "Myks helps to manage configuration for kubernetes clusters",
-		Long: `Myks fetches K8s workloads from a variety of sources, e.g. Helm charts or Git Repositories. It renders their respective yaml files to the file system in a structure of environments and their applications.
-
-	It supports prototype applications that can be shared between environments and inheritance of configuration from parent environments to their "children".
-
-	Myks supports two positional arguments:
-
-	- A comma-separated list of environments to render. If you provide "ALL", all environments will be rendered.
-	- A comma-separated list of applications to render. If you don't provide this argument or provide "ALL", all applications will be rendered.
-
-	If you do not provide any positional arguments, myks will run in "Smart Mode". In Smart Mode, myks will only render environments and applications that have changed since the last run.
-	`,
+		Short: "Myks generates Kubernetes manifests",
+		// TODO: Launch the documentation website and add a link here
+		Long: `
+Myks - Kubernetes Manifest Generator
+
+OVERVIEW
+  Myks simplifies Kubernetes manifest management through a standardized toolset
+  and GitOps-ready conventions.
+
+CORE FEATURES
+  • External source management (via vendir)
+  • Helm chart rendering
+  • YAML templating and validation (via ytt)
+  • Idempotent output
+  • Automatic ArgoCD resource generation
+  • Environment-based configuration inheritance
+  • Intelligent change detection
+
+BASIC COMMANDS
+  init     Create a new Myks project in the current directory
+  sync     Download external dependencies
+  render   Generate Kubernetes manifests
+  all      Perform sync and render in one step
+
+GETTING STARTED
+  1. Create a new project:    myks init
+  2. Download dependencies:   myks sync
+  3. Generate manifests:      myks render
+
+LEARN MORE
+  • Use 'myks <command> --help' for detailed information about a command
+  • Report issues at https://github.com/example/myks/issues
+`,
 	}
 
 	rootCmd.Version = fmt.Sprintf(`%s

diff --git a/cmd/sync.go b/cmd/sync.go
@@ -7,36 +7,32 @@ import (
 	"github.com/mykso/myks/internal/myks"
 )
 
-func newSyncCmd() *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "sync",
-		Short: "Sync vendir configs",
-		Long: `Sync vendir configs. This will run vendir sync for all applications.
+var syncCmd = &cobra.Command{
+	Use:   "sync",
+	Short: "Download external sources",
+	Long: `Download external sources for specified environments and applications.
 
 Authentication against protected repositories is achieved with environment variables prefixed with "VENDIR_SECRET_".
 For example, if you reference a secret named "mycreds" in your vendir.yaml, you need to export the variables "VENDIR_SECRET_MYCREDS_USERNAME" and
 "VENDIR_SECRET_MYCREDS_PASSWORD" in your environment.`,
-		Annotations: map[string]string{
-			ANNOTATION_SMART_MODE: ANNOTATION_TRUE,
-		},
-		Run: func(cmd *cobra.Command, args []string) {
-			log.Info().Msg("Syncing vendir configs")
-			g := myks.New(".")
-
-			if err := g.ValidateRootDir(); err != nil {
-				log.Fatal().Err(err).Msg("Root directory is not suitable for myks")
-			}
-
-			if err := g.Init(asyncLevel, envAppMap); err != nil {
-				log.Fatal().Err(err).Msg("Unable to initialize myks's globe")
-			}
-
-			if err := g.Sync(asyncLevel); err != nil {
-				log.Fatal().Err(err).Msg("Unable to sync vendir configs")
-			}
-		},
-		ValidArgsFunction: shellCompletion,
-	}
-
-	return cmd
+	Annotations: map[string]string{
+		ANNOTATION_SMART_MODE: ANNOTATION_TRUE,
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		log.Info().Msg("Syncing vendir configs")
+		g := myks.New(".")
+
+		if err := g.ValidateRootDir(); err != nil {
+			log.Fatal().Err(err).Msg("Root directory is not suitable for myks")
+		}
+
+		if err := g.Init(asyncLevel, envAppMap); err != nil {
+			log.Fatal().Err(err).Msg("Unable to initialize myks's globe")
+		}
+
+		if err := g.Sync(asyncLevel); err != nil {
+			log.Fatal().Err(err).Msg("Unable to sync vendir configs")
+		}
+	},
+	ValidArgsFunction: shellCompletion,
 }