From c597f6991f3fa4eba578c7fdc3c081a120d62a9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antti=20Kivim=C3=A4ki?= <antti.kivimaki@futurice.com>
Date: Thu, 21 Dec 2023 09:56:12 +0200
Subject: [PATCH] docs: support admonitions in command descriptions

---
 cmd/docs/main.go                | 30 +++++++++++++++++++++++++++++-
 cmd/docs/templates/_schema.tmpl |  2 +-
 internal/cli/execute.go         |  8 ++++++--
 internal/cli/option/values.go   |  2 +-
 internal/cli/upgrade.go         |  2 +-
 5 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/cmd/docs/main.go b/cmd/docs/main.go
index 71aa44d1..1c25c99e 100644
--- a/cmd/docs/main.go
+++ b/cmd/docs/main.go
@@ -5,6 +5,8 @@ import (
 	"embed"
 	"fmt"
 	"os"
+	"regexp"
+	"strings"
 	"text/template"
 
 	"github.com/Masterminds/sprig"
@@ -103,11 +105,14 @@ func checkErr(err error) {
 
 func mapCommandInfos(cmds []*cobra.Command) []CommandInfo {
 	infos := make([]CommandInfo, len(cmds))
+
 	for i, c := range cmds {
+		description := replaceAdmonition(c.Long)
+
 		info := CommandInfo{
 			Name:        c.Name(),
 			Aliases:     c.Aliases,
-			Description: c.Long,
+			Description: description,
 			Usage:       c.Use,
 			Example:     c.Example,
 			Flags:       make([]Flag, 0),
@@ -137,3 +142,26 @@ func valueTypeToString(v pflag.Value) string {
 		return t
 	}
 }
+
+var admonitionRegExp *regexp.Regexp = regexp.MustCompile("\n((Note|Tip|Info|Warning|Danger): (.+))")
+
+func replaceAdmonition(s string) string {
+	description := s
+	admonitions := admonitionRegExp.FindAllStringSubmatch(description, -1)
+	if len(admonitions) > 0 {
+		for _, a := range admonitions {
+			description = strings.Replace(
+				description,
+				a[0],
+				fmt.Sprintf(
+					"\n:::%s\n\n%s\n\n:::",
+					strings.ToLower(a[2]),
+					a[3],
+				),
+				1,
+			)
+		}
+	}
+
+	return description
+}
diff --git a/cmd/docs/templates/_schema.tmpl b/cmd/docs/templates/_schema.tmpl
index dd86899c..a95181bd 100644
--- a/cmd/docs/templates/_schema.tmpl
+++ b/cmd/docs/templates/_schema.tmpl
@@ -11,7 +11,7 @@
 | `templateExtension` | `string` | | File extension of files in "templates" directory which should be templated. Files not matched by this extension will be copied as-is. If left empty (the default), all files will be templated. |
 | `initHelp` | `string` | | A message which will be showed to an user after a succesful recipe execution. Can be used to guide the user what should be done next in the project directory. |
 | `ignorePatterns` | `[]string` | | Glob patterns for ignoring generated files from future recipe upgrades. Ignored files will not be regenerated even if their templates change in future versions of the recipe. |
-| `vars` | [`[]Variable`](#variable) | | An array of variables which can be used in templates. The user will be prompted to provide the value for the variable if not predefined with `--set` flag. |
+| `vars` | [`[]Variable`](#variable) | | An array of variables which can be used in templates. The user will be prompted to provide the value for the variable if not set with `--set` flag. |
 
 ### Variable
 
diff --git a/internal/cli/execute.go b/internal/cli/execute.go
index 3c4caa3a..e5638222 100644
--- a/internal/cli/execute.go
+++ b/internal/cli/execute.go
@@ -56,8 +56,12 @@ jalapeno execute oci://ghcr.io/user/my-recipe:latest
 # Execute recipe to different directory
 jalapeno execute path/to/recipe --dir other/dir
 
-# Predefine variable values
-jalapeno execute path/to/recipe --set MY_VAR=foo --set MY_OTHER_VAR=bar`,
+# Set variable values with flags
+jalapeno execute path/to/recipe --set MY_VAR=foo --set MY_OTHER_VAR=bar
+
+# Set variable values with environment variables
+export JALAPENO_VAR_MY_VAR=foo
+jalapeno execute path/to/recipe`,
 	}
 
 	if err := option.ApplyFlags(&opts, cmd.Flags()); err != nil {
diff --git a/internal/cli/option/values.go b/internal/cli/option/values.go
index 6aeea2a1..023e0c04 100644
--- a/internal/cli/option/values.go
+++ b/internal/cli/option/values.go
@@ -16,7 +16,7 @@ type Values struct {
 }
 
 func (opts *Values) ApplyFlags(fs *pflag.FlagSet) {
-	fs.StringArrayVarP(&opts.Flags, "set", "s", []string{}, "Predefine values to be used in the templates. Example: `--set \"MY_VAR=foo\"`")
+	fs.StringArrayVarP(&opts.Flags, "set", "s", []string{}, "Set values to be used in the templates. Example: `--set \"MY_VAR=foo\"`")
 	fs.StringVar(&opts.delimiter, "delimiter", ",", "Delimiter used when setting table variables")
 	fs.BoolVarP(&opts.ReuseSauceValues, "reuse-sauce-values", "r", false, "By default each sauce has their own set of values even if the variable names are same in both recipes. Setting this to `true` will reuse previous sauce values if the variable name match")
 	fs.BoolVar(&opts.NoInput, "no-input", false, "If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment")
diff --git a/internal/cli/upgrade.go b/internal/cli/upgrade.go
index 31a1d0a4..1baf4939 100644
--- a/internal/cli/upgrade.go
+++ b/internal/cli/upgrade.go
@@ -58,7 +58,7 @@ jalapeno upgrade oci://ghcr.io/user/my-recipe:v2.0.0
 # Upgrade recipe to different directory
 jalapeno upgrade path/to/recipe --dir other/dir
 
-# Predefine values for new variables introduced in the upgrade
+# Set values for new variables introduced in the upgrade
 jalapeno upgrade path/to/recipe --set NEW_VAR=foo`,
 	}