flag description should be rendered in markdown

cmd/atlantis_generate_repo_config.go

@@ -30,41 +30,28 @@ var atlantisGenerateRepoConfigCmd = &cobra.Command{
 func init() {
 	atlantisGenerateRepoConfigCmd.DisableFlagParsing = false
 
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("output-path", "", "atmos atlantis generate repo-config --output-path ./atlantis.yaml --config-template config-1 --project-template project-1")
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("config-template", "", "atmos atlantis generate repo-config --config-template config-1 --project-template project-1")
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("project-template", "", "atmos atlantis generate repo-config --config-template config-1 --project-template project-1")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("output-path", "", "Output path to write `atlantis.yaml` file")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("config-template", "", "Atlantis config template name")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("project-template", "", "Atlantis project template name")
 
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("stacks", "",
-		"Generate Atlantis projects for the specified stacks only (comma-separated values).\n"+
-			"atmos atlantis generate repo-config --config-template <config_template> --project-template <project_template> --stacks <stack1>,<stack2>\n"+
-			"The filter can contain the names of the top-level stack manifests and the logical stack names (derived from the context vars)\n"+
-			"atmos atlantis generate repo-config --config-template <config_template> --project-template <project_template> --stacks orgs/cp/tenant1/staging/us-east-2,orgs/cp/tenant2/dev/us-east-2\n"+
-			"atmos atlantis generate repo-config --config-template <config_template> --project-template <project_template> --stacks tenant1-ue2-staging,tenant1-ue2-prod\n"+
-			"atmos atlantis generate repo-config --config-template <config_template> --project-template <project_template> --stacks orgs/cp/tenant1/staging/us-east-2,tenant1-ue2-prod",
-	)
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("stacks", "", "Generate Atlantis projects for the specified stacks only (comma-separated values).")
 
 	atlantisGenerateRepoConfigCmd.PersistentFlags().String("components", "",
-		"Generate Atlantis projects for the specified components only (comma-separated values).\n"+
-			"atmos atlantis generate repo-config --config-template <config_template> --project-template <project_template> --components <component1>,<component2>",
+		"Generate Atlantis projects for the specified components only (comma-separated values).",
 	)
 
 	atlantisGenerateRepoConfigCmd.PersistentFlags().Bool("affected-only", false,
-		"Generate Atlantis projects only for the Atmos components changed between two Git commits.\n"+
-			"atmos atlantis generate repo-config --affected-only=true",
+		"Generate Atlantis projects only for the Atmos components changed between two Git commits.",
 	)
 
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("repo-path", "", "Filesystem path to the already cloned target repository with which to compare the current branch: atmos atlantis generate repo-config --affected-only=true --repo-path <path_to_already_cloned_repo>")
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("ref", "", "Git reference with which to compare the current branch: atmos atlantis generate repo-config --affected-only=true --ref refs/heads/main. Refer to https://git-scm.com/book/en/v2/Git-Internals-Git-References for more details")
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("sha", "", "Git commit SHA with which to compare the current branch: atmos atlantis generate repo-config --affected-only=true --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073")
-	atlantisGenerateRepoConfigCmd.PersistentFlags().Bool("verbose", false, "Print more detailed output when cloning and checking out the Git repository: atmos atlantis generate repo-config --affected-only=true --verbose=true")
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("ssh-key", "", "Path to PEM-encoded private key to clone private repos using SSH: atmos atlantis generate repo-config --affected-only=true --ssh-key <path_to_ssh_key>")
-	atlantisGenerateRepoConfigCmd.PersistentFlags().String("ssh-key-password", "", "Encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block: atmos atlantis generate repo-config --affected-only=true --ssh-key <path_to_ssh_key> --ssh-key-password <password>")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("repo-path", "", "Filesystem path to the already cloned target repository with which to compare the current branch")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("ref", "", "Git reference with which to compare the current branch. Refer to [10.3 Git Internals Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References) for more details")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("sha", "", "Git commit SHA with which to compare the current branch")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().Bool("verbose", false, "Print more detailed output when cloning and checking out the Git repository")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("ssh-key", "", "Path to PEM-encoded private key to clone private repos using SSH")
+	atlantisGenerateRepoConfigCmd.PersistentFlags().String("ssh-key-password", "", "Encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block")
 
-	atlantisGenerateCmd.PersistentFlags().Bool("clone-target-ref", false, "Clone the target reference with which to compare the current branch: "+
-		"atmos atlantis generate repo-config --affected-only=true --clone-target-ref=true\n"+
-		"The flag is only used when '--affected-only=true'\n"+
-		"If set to 'false' (default), the target reference will be checked out instead\n"+
-		"This requires that the target reference is already cloned by Git, and the information about it exists in the '.git' directory")
+	atlantisGenerateCmd.PersistentFlags().Bool("clone-target-ref", false, "Clone the target reference for comparison with the current branch. Only used when `--affected-only=true`. Defaults to false, which checks out the target reference instead.")
 
 	atlantisGenerateCmd.AddCommand(atlantisGenerateRepoConfigCmd)
 }

cmd/aws_eks_update_kubeconfig.go

@@ -10,24 +10,21 @@ import (
 // awsEksCmdUpdateKubeconfigCmd executes 'aws eks update-kubeconfig' command
 var awsEksCmdUpdateKubeconfigCmd = &cobra.Command{
 	Use:   "update-kubeconfig",
-	Short: "Update 'kubeconfig' for an EKS cluster using AWS CLI",
-	Long: `This command executes 'aws eks update-kubeconfig' to download 'kubeconfig' from an EKS cluster and saves it to a file. The command executes 'aws eks update-kubeconfig' in three different ways:
+	Short: "Update `kubeconfig` for an EKS cluster using AWS CLI",
+	Long: `This command executes ` + "`" + `aws eks update-kubeconfig` + "`" + ` to download ` + "`" + `kubeconfig` + "`" + ` from an EKS cluster and saves it to a file. The command executes ` + "`" + `aws eks update-kubeconfig` + "`" + ` in three different ways:
 
 1. If all the required parameters (cluster name and AWS profile/role) are provided on the command-line,
-then 'atmos' executes the command without requiring the 'atmos.yaml' CLI config and context.
-For example: atmos aws eks update-kubeconfig --profile=<profile> --name=<cluster_name>
+then ` + "`" + `atmos` + "`" + ` executes the command without requiring the ` + "`" + `atmos.yaml` + "`" + ` CLI config and context.
 
 2. If 'component' and 'stack' are provided on the command-line,
-   then 'atmos' executes the command using the 'atmos.yaml' CLI config and stack's context by searching for the following settings:
+   then ` + "`" + `atmos` + "`" + ` executes the command using the ` + "`" + `atmos.yaml` + "`" + ` CLI config and stack's context by searching for the following settings:
   - 'components.helmfile.cluster_name_pattern' in the 'atmos.yaml' CLI config (and calculates the '--name' parameter using the pattern)
-  - 'components.helmfile.helm_aws_profile_pattern' in the 'atmos.yaml' CLI config (and calculates the '--profile' parameter using the pattern)
+  - 'components.helmfile.helm_aws_profile_pattern' in the 'atmos.yaml' CLI config (and calculates the ` + "`" + `--profile` + "`" + ` parameter using the pattern)
   - 'components.helmfile.kubeconfig_path' in the 'atmos.yaml' CLI config
   - the variables for the component in the provided stack
   - 'region' from the variables for the component in the stack
-For example: atmos aws eks update-kubeconfig <component> -s <stack>
 
 3. Combination of the above. Provide a component and a stack, and override other parameters on the command line.
-For example: atmos aws eks update-kubeconfig <component> -s <stack> --kubeconfig=<path_to_kubeconfig> --region=<region>
 
 See https://docs.aws.amazon.com/cli/latest/reference/eks/update-kubeconfig.html for more information.`,
 
@@ -44,16 +41,15 @@ See https://docs.aws.amazon.com/cli/latest/reference/eks/update-kubeconfig.html
 // https://docs.aws.amazon.com/cli/latest/reference/eks/update-kubeconfig.html
 func init() {
 	awsEksCmdUpdateKubeconfigCmd.DisableFlagParsing = false
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().StringP("stack", "s", "", "atmos aws eks update-kubeconfig <component> -s <stack>")
 	AddStackCompletion(awsEksCmdUpdateKubeconfigCmd)
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("profile", "", "atmos aws eks update-kubeconfig --profile <profile>")
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("name", "", "atmos aws eks update-kubeconfig --name <cluster name>")
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("region", "", "atmos aws eks update-kubeconfig --region <region>")
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("kubeconfig", "", "atmos aws eks update-kubeconfig --kubeconfig <path_to_kubeconfig>")
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("role-arn", "", "atmos aws eks update-kubeconfig --role-arn <ARN>")
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().Bool("dry-run", false, "atmos aws eks update-kubeconfig --dry-run=true")
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().Bool("verbose", false, "atmos aws eks update-kubeconfig --verbose=true")
-	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("alias", "", "atmos aws eks update-kubeconfig --alias <alias for the cluster context name>")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("profile", "", "Specify the AWS CLI profile to use for authentication")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("name", "", "Specify the name of the EKS cluster to update the kubeconfig for")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("region", "", "Specify the AWS region where the EKS cluster is located")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("kubeconfig", "", "Specify the path to the kubeconfig file to be updated or created for accessing the EKS cluster.")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("role-arn", "", "Specify the ARN of the IAM role to assume for authenticating with the EKS cluster.")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().Bool("dry-run", false, "Perform a dry run to simulate updating the kubeconfig without making any changes.")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().Bool("verbose", false, "Enable verbose logging to provide detailed output during the kubeconfig update process.")
+	awsEksCmdUpdateKubeconfigCmd.PersistentFlags().String("alias", "", "Specify an alias to use for the cluster context name in the kubeconfig file.")
 
 	awsEksCmd.AddCommand(awsEksCmdUpdateKubeconfigCmd)
 }

cmd/cmd_utils.go

@@ -80,7 +80,7 @@ func processCustomCommands(
 				},
 			}
 			// TODO: we need to update this post https://github.com/cloudposse/atmos/pull/959 gets merged
-			customCommand.PersistentFlags().Bool("", false, "Use double dashes to separate Atmos-specific options from native arguments and flags for the command.")
+			customCommand.PersistentFlags().Bool("", false, doubleDashHint)
 			// Process and add flags to the command
 			for _, flag := range commandConfig.Flags {
 				if flag.Type == "bool" {
@@ -166,7 +166,7 @@ func processCommandAliases(
 
 		if _, exist := existingTopLevelCommands[alias]; !exist && topLevel {
 			aliasCmd := strings.TrimSpace(v)
-			aliasFor := fmt.Sprintf("alias for '%s'", aliasCmd)
+			aliasFor := fmt.Sprintf("alias for `%s`", aliasCmd)
 
 			aliasCommand := &cobra.Command{
 				Use:                alias,
@@ -695,7 +695,7 @@ func showErrorExampleFromMarkdown(cmd *cobra.Command, arg string) {
 }
 
 func showUsageExample(cmd *cobra.Command, details string) {
-	contentName := strings.ReplaceAll(cmd.CommandPath(), " ", "_")
+	contentName := strings.ReplaceAll(strings.ReplaceAll(cmd.CommandPath(), " ", "_"), "-", "_")
 	suggestion := fmt.Sprintf("\n\nRun `%s --help` for usage", cmd.CommandPath())
 	if exampleContent, ok := examples[contentName]; ok {
 		suggestion = exampleContent.Suggestion
@@ -713,6 +713,9 @@ func stackFlagCompletion(cmd *cobra.Command, args []string, toComplete string) (
 }
 
 func AddStackCompletion(cmd *cobra.Command) {
+	if cmd.Flag("stack") == nil {
+		cmd.PersistentFlags().StringP("stack", "s", "", stackHint)
+	}
 	cmd.RegisterFlagCompletionFunc("stack", stackFlagCompletion)
 }
 

cmd/describe.go

@@ -14,6 +14,6 @@ var describeCmd = &cobra.Command{
 }
 
 func init() {
-	describeCmd.PersistentFlags().StringP("query", "q", "", "Query the results of an 'atmos describe' command using 'yq' expressions: atmos describe <subcommand> --query <yq-expression>")
+	describeCmd.PersistentFlags().StringP("query", "q", "", "Query the results of an `atmos describe` command using `yq` expressions")
 	RootCmd.AddCommand(describeCmd)
 }

cmd/describe_affected.go

@@ -28,27 +28,26 @@ var describeAffectedCmd = &cobra.Command{
 func init() {
 	describeAffectedCmd.DisableFlagParsing = false
 
-	describeAffectedCmd.PersistentFlags().String("repo-path", "", "Filesystem path to the already cloned target repository with which to compare the current branch: atmos describe affected --repo-path <path_to_already_cloned_repo>")
-	describeAffectedCmd.PersistentFlags().String("ref", "", "Git reference with which to compare the current branch: atmos describe affected --ref refs/heads/main. Refer to https://git-scm.com/book/en/v2/Git-Internals-Git-References for more details")
-	describeAffectedCmd.PersistentFlags().String("sha", "", "Git commit SHA with which to compare the current branch: atmos describe affected --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073")
-	describeAffectedCmd.PersistentFlags().String("file", "", "Write the result to the file: atmos describe affected --ref refs/tags/v1.75.0 --file affected.json")
-	describeAffectedCmd.PersistentFlags().String("format", "json", "The output format: atmos describe affected --format=json|yaml ('json' is default)")
-	describeAffectedCmd.PersistentFlags().Bool("verbose", false, "Print more detailed output when cloning and checking out the Git repository: atmos describe affected --verbose=true")
-	describeAffectedCmd.PersistentFlags().String("ssh-key", "", "Path to PEM-encoded private key to clone private repos using SSH: atmos describe affected --ssh-key <path_to_ssh_key>")
-	describeAffectedCmd.PersistentFlags().String("ssh-key-password", "", "Encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block: atmos describe affected --ssh-key <path_to_ssh_key> --ssh-key-password <password>")
-	describeAffectedCmd.PersistentFlags().Bool("include-spacelift-admin-stacks", false, "Include the Spacelift admin stack of any stack that is affected by config changes: atmos describe affected --include-spacelift-admin-stacks=true")
-	describeAffectedCmd.PersistentFlags().Bool("include-dependents", false, "Include the dependent components and stacks: atmos describe affected --include-dependents=true")
-	describeAffectedCmd.PersistentFlags().Bool("include-settings", false, "Include the 'settings' section for each affected component: atmos describe affected --include-settings=true")
-	describeAffectedCmd.PersistentFlags().Bool("upload", false, "Upload the affected components and stacks to a specified HTTP endpoint: atmos describe affected --upload=true")
-	describeAffectedCmd.PersistentFlags().StringP("stack", "s", "", "atmos describe affected -s <stack>")
+	describeAffectedCmd.PersistentFlags().String("repo-path", "", "Filesystem path to the already cloned target repository with which to compare the current branch")
+	describeAffectedCmd.PersistentFlags().String("ref", "", "Git reference with which to compare the current branch. Refer to [10.3 Git Internals Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References) for more details")
+	describeAffectedCmd.PersistentFlags().String("sha", "", "Git commit SHA with which to compare the current branch")
+	describeAffectedCmd.PersistentFlags().String("file", "", "Write the result to the file")
+	describeAffectedCmd.PersistentFlags().String("format", "json", "The output format. (`json` is default)")
+	describeAffectedCmd.PersistentFlags().Bool("verbose", false, "Print more detailed output when cloning and checking out the Git repository")
+	describeAffectedCmd.PersistentFlags().String("ssh-key", "", "Path to PEM-encoded private key to clone private repos using SSH")
+	describeAffectedCmd.PersistentFlags().String("ssh-key-password", "", "Encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block")
+	describeAffectedCmd.PersistentFlags().Bool("include-spacelift-admin-stacks", false, "Include the Spacelift admin stack of any stack that is affected by config changes")
+	describeAffectedCmd.PersistentFlags().Bool("include-dependents", false, "Include the dependent components and stacks")
+	describeAffectedCmd.PersistentFlags().Bool("include-settings", false, "Include the `settings` section for each affected component")
+	describeAffectedCmd.PersistentFlags().Bool("upload", false, "Upload the affected components and stacks to a specified HTTP endpoint")
 	AddStackCompletion(describeAffectedCmd)
-	describeAffectedCmd.PersistentFlags().Bool("clone-target-ref", false, "Clone the target reference with which to compare the current branch: atmos describe affected --clone-target-ref=true\n"+
-		"If set to 'false' (default), the target reference will be checked out instead\n"+
-		"This requires that the target reference is already cloned by Git, and the information about it exists in the '.git' directory")
+	describeAffectedCmd.PersistentFlags().Bool("clone-target-ref", false, "Clone the target reference with which to compare the current branch\n"+
+		"If set to `false` (default), the target reference will be checked out instead\n"+
+		"This requires that the target reference is already cloned by Git, and the information about it exists in the `.git` directory")
 
-	describeAffectedCmd.PersistentFlags().Bool("process-templates", true, "Enable/disable Go template processing in Atmos stack manifests when executing the command: atmos describe affected --process-templates=false")
-	describeAffectedCmd.PersistentFlags().Bool("process-functions", true, "Enable/disable YAML functions processing in Atmos stack manifests when executing the command: atmos describe affected --process-functions=false")
-	describeAffectedCmd.PersistentFlags().StringSlice("skip", nil, "Skip executing a YAML function when processing Atmos stack manifests: atmos describe affected --skip=terraform.output")
+	describeAffectedCmd.PersistentFlags().Bool("process-templates", true, "Enable/disable Go template processing in Atmos stack manifests when executing the command")
+	describeAffectedCmd.PersistentFlags().Bool("process-functions", true, "Enable/disable YAML functions processing in Atmos stack manifests when executing the command")
+	describeAffectedCmd.PersistentFlags().StringSlice("skip", nil, "Skip executing a YAML function when processing Atmos stack manifests")
 
 	describeCmd.AddCommand(describeAffectedCmd)
 }