feat: support custom output filenames (#19)

twelvelabs · Dec 17, 2023 · d86eb62 · d86eb62
1 parent 22c440d
commit d86eb62
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -24,14 +24,35 @@ Choose one of the following:
 
 ## Usage
 
-```bash
+```shell
 # Renders `./my.schema.json` to `./out/SchemaTitle.md`.
 schemadoc gen --in ./my.schema.json
 
 # Renders all json schema files in `./schemas` to `./docs`.
 schemadoc gen --in ./schemas --out ./docs
 ```
 
+To see schemadoc in action, check out
+[Generator.md](https://github.com/twelvelabs/stamp/blob/main/docs/Generator.md)
+which is rendered from
+[stamp.schema.json](https://github.com/twelvelabs/stamp/blob/main/docs/stamp.schema.json)
+at build time.
+
+## Customizing
+
+Schemadoc ships with a built in [template](./internal/jsonschema/templates/markdown.tpl.md) for rendering markdown.
+To customize (or render something other than markdown)
+you can supply your own Go [text/template](https://pkg.go.dev/text/template) file:
+
+```shell
+schemadoc gen --in ./schemas --out ./dest --template path/to/my-xml-template.tpl --outfile "{{ .EntityName }}.xml"
+```
+
+Each top-level JSON schema in `./schemas` will be parsed into a
+[Schema](./internal/jsonschema/schema.go) struct and passed into
+`my-xml-template.tpl`.
+The rendered files will be written to `./dest/$SchemaName.xml`.
+
 ## Development
 
 ```shell

diff --git a/internal/cmd/gen.go b/internal/cmd/gen.go
@@ -29,6 +29,9 @@ func NewGenCmd(app *core.App) *cobra.Command {
 	a := &GenAction{
 		App: app,
 	}
+	if err := defaults.Set(a); err != nil {
+		panic(err)
+	}
 
 	cmd := &cobra.Command{
 		Use:   "gen",
@@ -42,7 +45,8 @@ func NewGenCmd(app *core.App) *cobra.Command {
 	flags := cmd.Flags()
 	flags.StringVarP(&a.InPath, "in", "i", a.InPath, "file path or dir to one or more JSON schema files")
 	flags.StringVarP(&a.OutDir, "out", "o", a.OutDir, "output dir to generate files to")
-	flags.StringVarP(&a.TemplatePath, "template", "t", a.TemplatePath, "optional template path")
+	flags.StringVarP(&a.OutFile, "outfile", "f", a.OutFile, "custom filename pattern for generated files")
+	flags.StringVarP(&a.TemplatePath, "template", "t", a.TemplatePath, "custom template path")
 
 	return cmd
 }
@@ -52,6 +56,7 @@ type GenAction struct {
 
 	InPath       string `validate:"required"`
 	OutDir       string `validate:"required" default:"out"`
+	OutFile      string `validate:"required" default:"{{ .EntityName }}.md"`
 	SchemaPaths  []string
 	TemplatePath string
 }
@@ -93,8 +98,12 @@ func (a *GenAction) Run(_ context.Context, _ []string) error {
 			return err
 		}
 
-		renderedPath := filepath.Join(a.OutDir, fmt.Sprintf("%s.md", scm.EntityName()))
-		if err := os.WriteFile(renderedPath, []byte(rendered), fsutil.DefaultFileMode); err != nil {
+		outFile, err := render.String(a.OutFile, scm)
+		if err != nil {
+			return err
+		}
+		outPath := filepath.Join(a.OutDir, outFile)
+		if err := os.WriteFile(outPath, []byte(rendered), fsutil.DefaultFileMode); err != nil {
 			return err
 		}
 	}
@@ -105,13 +114,11 @@ func (a *GenAction) Run(_ context.Context, _ []string) error {
 func (a *GenAction) setup() error {
 	start := time.Now()
 
-	if err := defaults.Set(a); err != nil {
-		return err
-	}
 	if err := validate.Struct(a); err != nil {
 		msg := err.Error()
 		msg = strings.ReplaceAll(msg, "InPath", `'--in'`)
 		msg = strings.ReplaceAll(msg, "OutDir", `'--out'`)
+		msg = strings.ReplaceAll(msg, "OutFile", `'--outfile'`)
 		msg = strings.ReplaceAll(msg, "field", "flag")
 		return fmt.Errorf(msg)
 	}
@@ -150,6 +157,7 @@ func (a *GenAction) setup() error {
 		"duration", time.Since(start),
 		"in", a.SchemaPaths,
 		"out", a.OutDir,
+		"outfile", a.OutFile,
 		"template", a.TemplatePath,
 	)
 	return nil