[gen-readme] Allow custom templates (#1794)

## Summary

This adds:

Flag that saves default template
```
devbox generate readme [path] --save-template
```

Flag that uses custom template
```
devbox generate readme [path] --template <custom-template>
```

It also:

* defaults readme [path] to `README.md`
* defaults template [path] to `readme.tmpl`
* If there is `readme.tmpl` in root, then `devbox generate readme` will
use it automatically.
* Fixed missing env vars from default template

## How was it tested?

```
devbox generate readme --save-template # generate template
vi readme.tmpl # modified template
devbox generate readme devbox.md # tested creating new readme
```

Author: mikeland73

devbox.md

@@ -36,6 +36,13 @@ Scripts are custom commands that can be run using this project's environment. Th
 * [tidy](#devbox-run-tidy)
 * [update-examples](#devbox-run-update-examples)
 
+## Environment
+
+```sh
+GOENV="off"
+PATH="$PATH:$PWD/dist"
+```
+
 ## Shell Init Hook
 The Shell Init Hook is a script that runs whenever the devbox environment is instantiated. It runs 
 on `devbox shell` and on `devbox run`.

internal/boxcli/generate.go

@@ -22,6 +22,12 @@ type generateCmdFlags struct {
 	rootUser          bool
 }
 
+type GenerateReadmeCmdFlags struct {
+	generateCmdFlags
+	saveTemplate bool
+	template     string
+}
+
 func generateCmd() *cobra.Command {
 	flags := &generateCmdFlags{}
 
@@ -140,11 +146,12 @@ func sshConfigCmd() *cobra.Command {
 }
 
 func genReadmeCmd() *cobra.Command {
-	flags := &generateCmdFlags{}
+	flags := &GenerateReadmeCmdFlags{}
+
 	command := &cobra.Command{
 		Use:   "readme [filename]",
 		Short: "Generate markdown readme file for this project",
-		Args:  cobra.ExactArgs(1),
+		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			box, err := devbox.Open(&devopt.Opts{
 				Dir:         flags.config.path,
@@ -154,10 +161,22 @@ func genReadmeCmd() *cobra.Command {
 			if err != nil {
 				return errors.WithStack(err)
 			}
-			return docgen.GenerateReadme(box, args[0])
+			outPath := ""
+			if len(args) > 0 {
+				outPath = args[0]
+			}
+			if flags.saveTemplate {
+				return docgen.SaveDefaultReadmeTemplate(outPath)
+			}
+			return docgen.GenerateReadme(box, outPath, flags.template)
 		},
 	}
 	flags.config.register(command)
+	command.Flags().BoolVar(
+		&flags.saveTemplate, "save-template", false, "Save default template for the README file")
+	command.Flags().StringVarP(
+		&flags.template, "template", "t", "", "Path to a custom template for the README file")
+
 	return command
 }
 

internal/devbox/docgen/docgen.go

@@ -6,23 +6,51 @@ import (
 	"text/template"
 
 	"go.jetpack.io/devbox/internal/devbox"
+	"go.jetpack.io/devbox/internal/fileutil"
 )
 
 //go:embed readme.tmpl
-var readmeTemplate string
+var defaultReadmeTemplate string
 
-func GenerateReadme(devbox *devbox.Devbox, path string) error {
-	t, err := template.New("readme").Parse(readmeTemplate)
+const (
+	defaultName         = "README.md"
+	defaultTemplateName = "readme.tmpl"
+)
+
+func GenerateReadme(
+	devbox *devbox.Devbox,
+	outputPath, templatePath string,
+) error {
+	readmeTemplate := defaultReadmeTemplate
+	if templatePath != "" {
+		readmeTemplateBytes, err := os.ReadFile(templatePath)
+		if err != nil {
+			return err
+		}
+		readmeTemplate = string(readmeTemplateBytes)
+	} else if fileutil.Exists(defaultTemplateName) {
+		readmeTemplateBytes, err := os.ReadFile(defaultTemplateName)
+		if err != nil {
+			return err
+		}
+		readmeTemplate = string(readmeTemplateBytes)
+	}
+
+	tmpl, err := template.New("readme").Parse(readmeTemplate)
 	if err != nil {
 		return err
 	}
 
-	f, err := os.Create(path)
+	if outputPath == "" {
+		outputPath = defaultName
+	}
+
+	f, err := os.Create(outputPath)
 	if err != nil {
 		return err
 	}
 
-	return t.Execute(f, map[string]any{
+	return tmpl.Execute(f, map[string]any{
 		"Name":        devbox.Config().Name,
 		"Description": devbox.Config().Description,
 		"Scripts":     devbox.Config().Scripts(),
@@ -31,3 +59,10 @@ func GenerateReadme(devbox *devbox.Devbox, path string) error {
 		"Packages":    devbox.ConfigPackages(),
 	})
 }
+
+func SaveDefaultReadmeTemplate(outputPath string) error {
+	if outputPath == "" {
+		outputPath = defaultTemplateName
+	}
+	return os.WriteFile(outputPath, []byte(defaultReadmeTemplate), 0o644)
+}

internal/devbox/docgen/readme.tmpl

@@ -33,11 +33,11 @@ Scripts are custom commands that can be run using this project's environment. Th
 {{- end }}
 {{ end }}
 
-{{- if .Env }}
+{{- if .EnvVars }}
 ## Environment
 
 ```sh
-{{- range $key, $value := .Env }}
+{{- range $key, $value := .EnvVars }}
 {{ $key }}="{{ $value }}"
 {{- end }}
 ```