From a3d4f442b09a5bb2f30cb0d6552fefec3dc2731d Mon Sep 17 00:00:00 2001 From: Rodion Stolyarov Date: Sun, 5 Jan 2025 12:59:19 +0700 Subject: [PATCH 1/3] Add support for json output format --- README.md | 2 +- render/config.go | 4 ++++ render/renderer.go | 18 +++++++++--------- render/templ/json.tmpl | 3 +++ render/templates.go | 5 +++++ types/model.go | 1 + 6 files changed, 23 insertions(+), 10 deletions(-) create mode 100644 render/templ/json.tmpl diff --git a/README.md b/README.md index ff82ad6..6916da2 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ type Config struct { * `-files` (glob string, *optional*) - File glob pattern to specify file names to process. Default is the single file with `go:generate`. * `-types` (glob string, *optional*) - Type glob pattern for type names to process. If not specified, the next type after `go:generate` is used. * `-output` (path string, **required**) - Output file name for generated documentation. - * `-format` (`enum(markdown, plaintext, html, dotenv)` string, *optional*) - Output format for documentation. Default is `markdown`. + * `-format` (`enum(markdown, plaintext, html, dotenv, json)` string, *optional*) - Output format for documentation. Default is `markdown`. * `-no-styles` (`bool`, *optional*) - If true, CSS styles will not be included for `html` format. * `-env-prefix` (`string`, *optional*) - Sets additional global prefix for all environment variables. * `-tag-name` (string, *optional*, default: `env`) - Use custom tag name instead of `env`. diff --git a/render/config.go b/render/config.go index de02796..47db92e 100644 --- a/render/config.go +++ b/render/config.go @@ -65,4 +65,8 @@ var configs = map[types.OutFormat]renderConfig{ }, tmpl: newTmplText("dotenv.tmpl"), }, + types.OutFormatJSON: { + Item: renderItemConfig{}, + tmpl: newTmplText("json.tmpl"), + }, } diff --git a/render/renderer.go b/render/renderer.go index 7c7a831..84a1f1a 100644 --- a/render/renderer.go +++ b/render/renderer.go @@ -41,18 +41,18 @@ type renderSection struct { } type renderItem struct { - EnvName string - Doc string - EnvDefault string - EnvSeparator string + EnvName string `json:"env_name"` + Doc string `json:"doc"` + EnvDefault string `json:"env_default"` + EnvSeparator string `json:"env_separator"` - Required bool - Expand bool - NonEmpty bool - FromFile bool + Required bool `json:"required"` + Expand bool `json:"expand"` + NonEmpty bool `json:"non_empty"` + FromFile bool `json:"from_file"` children []renderItem - Indent int + Indent int `json:"-"` } func (i renderItem) Children(indentInc int) []renderItem { diff --git a/render/templ/json.tmpl b/render/templ/json.tmpl new file mode 100644 index 0000000..5e09b05 --- /dev/null +++ b/render/templ/json.tmpl @@ -0,0 +1,3 @@ +{{- range .Sections }} +{{- marshal .Items }} +{{- end }} diff --git a/render/templates.go b/render/templates.go index 325fbe8..06465d1 100644 --- a/render/templates.go +++ b/render/templates.go @@ -2,6 +2,7 @@ package render import ( "embed" + "encoding/json" "path" "strings" @@ -31,6 +32,10 @@ var tplFuncs = map[string]any{ } return sum }, + "marshal": func(v any) string { + a, _ := json.Marshal(v) + return string(a) + }, } const ( diff --git a/types/model.go b/types/model.go index 20ddb17..11879af 100644 --- a/types/model.go +++ b/types/model.go @@ -8,6 +8,7 @@ const ( OutFormatHTML OutFormat = "html" OutFormatTxt OutFormat = "plaintext" OutFormatEnv OutFormat = "dotenv" + OutFormatJSON OutFormat = "json" ) // EnvDocItem is a documentation item for one environment variable. From 9f66e7412478b1e507a7f96652eff36797060221 Mon Sep 17 00:00:00 2001 From: Rodion Stolyarov Date: Tue, 7 Jan 2025 19:03:40 +0700 Subject: [PATCH 2/3] Minor changes - add an example for json format - update marshal function to return an error --- _examples/simple/config.go | 1 + _examples/simple/doc.json | 1 + render/templates.go | 6 +++--- 3 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 _examples/simple/doc.json diff --git a/_examples/simple/config.go b/_examples/simple/config.go index a919c7e..c46104f 100644 --- a/_examples/simple/config.go +++ b/_examples/simple/config.go @@ -8,6 +8,7 @@ package main //go:generate go run ../../ -output doc.md -format markdown //go:generate go run ../../ -output doc.html -format html //go:generate go run ../../ -output doc.env -format dotenv +//go:generate go run ../../ -output doc.json -format json type Config struct { // Hosts name of hosts to listen on. Hosts []string `env:"HOST,required", envSeparator:";"` diff --git a/_examples/simple/doc.json b/_examples/simple/doc.json new file mode 100644 index 0000000..f8113fa --- /dev/null +++ b/_examples/simple/doc.json @@ -0,0 +1 @@ +[{"env_name":"HOST","doc":"Hosts name of hosts to listen on.","env_default":"","env_separator":";","required":true,"expand":false,"non_empty":false,"from_file":false},{"env_name":"PORT","doc":"Port to listen on.","env_default":"","env_separator":"","required":true,"expand":false,"non_empty":true,"from_file":false},{"env_name":"DEBUG","doc":"Debug mode enabled.","env_default":"false","env_separator":"","required":false,"expand":false,"non_empty":false,"from_file":false},{"env_name":"PREFIX","doc":"Prefix for something.","env_default":"","env_separator":"","required":false,"expand":false,"non_empty":false,"from_file":false}] diff --git a/render/templates.go b/render/templates.go index 06465d1..c587253 100644 --- a/render/templates.go +++ b/render/templates.go @@ -32,9 +32,9 @@ var tplFuncs = map[string]any{ } return sum }, - "marshal": func(v any) string { - a, _ := json.Marshal(v) - return string(a) + "marshal": func(v any) (string, error) { + a, err := json.Marshal(v) + return string(a), err }, } From 2af50da6edf8d2f9e1478f0f08f1c0b699762d2f Mon Sep 17 00:00:00 2001 From: Rodion Stolyarov Date: Thu, 9 Jan 2025 20:53:58 +0700 Subject: [PATCH 3/3] Format JSON output with indents --- _examples/simple/doc.json | 24 +++++++++++++++++++++++- render/renderer.go | 12 ++++++------ render/templ/json.tmpl | 2 +- render/templates.go | 4 ++-- 4 files changed, 32 insertions(+), 10 deletions(-) diff --git a/_examples/simple/doc.json b/_examples/simple/doc.json index f8113fa..5f7bd52 100644 --- a/_examples/simple/doc.json +++ b/_examples/simple/doc.json @@ -1 +1,23 @@ -[{"env_name":"HOST","doc":"Hosts name of hosts to listen on.","env_default":"","env_separator":";","required":true,"expand":false,"non_empty":false,"from_file":false},{"env_name":"PORT","doc":"Port to listen on.","env_default":"","env_separator":"","required":true,"expand":false,"non_empty":true,"from_file":false},{"env_name":"DEBUG","doc":"Debug mode enabled.","env_default":"false","env_separator":"","required":false,"expand":false,"non_empty":false,"from_file":false},{"env_name":"PREFIX","doc":"Prefix for something.","env_default":"","env_separator":"","required":false,"expand":false,"non_empty":false,"from_file":false}] +[ + { + "env_name": "HOST", + "doc": "Hosts name of hosts to listen on.", + "env_separator": ";", + "required": true + }, + { + "env_name": "PORT", + "doc": "Port to listen on.", + "required": true, + "non_empty": true + }, + { + "env_name": "DEBUG", + "doc": "Debug mode enabled.", + "env_default": "false" + }, + { + "env_name": "PREFIX", + "doc": "Prefix for something." + } +] diff --git a/render/renderer.go b/render/renderer.go index 84a1f1a..7e74ba9 100644 --- a/render/renderer.go +++ b/render/renderer.go @@ -43,13 +43,13 @@ type renderSection struct { type renderItem struct { EnvName string `json:"env_name"` Doc string `json:"doc"` - EnvDefault string `json:"env_default"` - EnvSeparator string `json:"env_separator"` + EnvDefault string `json:"env_default,omitempty"` + EnvSeparator string `json:"env_separator,omitempty"` - Required bool `json:"required"` - Expand bool `json:"expand"` - NonEmpty bool `json:"non_empty"` - FromFile bool `json:"from_file"` + Required bool `json:"required,omitempty"` + Expand bool `json:"expand,omitempty"` + NonEmpty bool `json:"non_empty,omitempty"` + FromFile bool `json:"from_file,omitempty"` children []renderItem Indent int `json:"-"` diff --git a/render/templ/json.tmpl b/render/templ/json.tmpl index 5e09b05..05b2ada 100644 --- a/render/templ/json.tmpl +++ b/render/templ/json.tmpl @@ -1,3 +1,3 @@ {{- range .Sections }} -{{- marshal .Items }} +{{- marshalIndent .Items }} {{- end }} diff --git a/render/templates.go b/render/templates.go index c587253..49d9332 100644 --- a/render/templates.go +++ b/render/templates.go @@ -32,8 +32,8 @@ var tplFuncs = map[string]any{ } return sum }, - "marshal": func(v any) (string, error) { - a, err := json.Marshal(v) + "marshalIndent": func(v any) (string, error) { + a, err := json.MarshalIndent(v, "", " ") return string(a), err }, }