cmd/doc: added support for json

Signed-off-by: Sam Alba <sam.alba@gmail.com>
This commit is contained in:
Sam Alba 2021-06-03 17:40:27 +02:00
parent dd8aae893c
commit 3b92f70416

View File

@ -2,6 +2,7 @@ package cmd
import ( import (
"context" "context"
"encoding/json"
"fmt" "fmt"
"io/fs" "io/fs"
"os" "os"
@ -24,9 +25,31 @@ import (
const ( const (
textFormat = "txt" textFormat = "txt"
markdownFormat = "md" markdownFormat = "md"
jsonFormat = "json"
textPadding = " " textPadding = " "
) )
// types used for json generation
type ValueJSON struct {
Name string
Type string
Description string
}
type FieldJSON struct {
Name string
Description string
Inputs []ValueJSON
Outputs []ValueJSON
}
type PackageJSON struct {
Name string
Description string
Fields []FieldJSON
}
var docCmd = &cobra.Command{ var docCmd = &cobra.Command{
Use: "doc [PACKAGE | PATH]", Use: "doc [PACKAGE | PATH]",
Short: "document a package", Short: "document a package",
@ -43,8 +66,10 @@ var docCmd = &cobra.Command{
ctx := lg.WithContext(cmd.Context()) ctx := lg.WithContext(cmd.Context())
format := viper.GetString("output") format := viper.GetString("output")
if format != textFormat && format != markdownFormat { if format != textFormat &&
lg.Fatal().Msg("output must be either `txt` or `md`") format != markdownFormat &&
format != jsonFormat {
lg.Fatal().Msg("output must be either `txt`, `md` or `json`")
} }
packageName := args[0] packageName := args[0]
@ -133,6 +158,21 @@ func printValuesMarkdown(libName string, values []*compiler.Value) {
w.Flush() w.Flush()
} }
// printValuesJson fills a struct for json output
func valuesToJSON(libName string, values []*compiler.Value) []ValueJSON {
val := []ValueJSON{}
for _, i := range values {
v := ValueJSON{}
v.Name = formatLabel(libName, i)
v.Type = common.FormatValue(i)
v.Description = common.ValueDocString(i)
val = append(val, v)
}
return val
}
func PrintDoc(ctx context.Context, packageName string, val *compiler.Value, format string) { func PrintDoc(ctx context.Context, packageName string, val *compiler.Value, format string) {
lg := log.Ctx(ctx) lg := log.Ctx(ctx)
@ -141,11 +181,12 @@ func PrintDoc(ctx context.Context, packageName string, val *compiler.Value, form
lg.Fatal().Err(err).Msg("cannot get fields") lg.Fatal().Err(err).Msg("cannot get fields")
} }
// Print title packageJSON := &PackageJSON{}
// Package Name + Description
switch format { switch format {
case textFormat: case textFormat:
fmt.Printf("Package %s\n", packageName) fmt.Printf("Package %s\n", packageName)
fmt.Printf("\n%s\n\n", common.ValueDocString(val)) fmt.Printf("\n%s\n", common.ValueDocString(val))
case markdownFormat: case markdownFormat:
fmt.Printf("## Package %s\n", mdEscape(packageName)) fmt.Printf("## Package %s\n", mdEscape(packageName))
comment := common.ValueDocString(val) comment := common.ValueDocString(val)
@ -154,10 +195,18 @@ func PrintDoc(ctx context.Context, packageName string, val *compiler.Value, form
break break
} }
fmt.Printf("\n%s\n\n", mdEscape(comment)) fmt.Printf("\n%s\n\n", mdEscape(comment))
case jsonFormat:
packageJSON.Name = packageName
comment := common.ValueDocString(val)
if comment != "" {
packageJSON.Description = comment
}
} }
// Package Fields // Package Fields
for _, field := range fields { for _, field := range fields {
fieldJSON := FieldJSON{}
if !field.Selector.IsDefinition() { if !field.Selector.IsDefinition() {
// not a definition, skipping // not a definition, skipping
continue continue
@ -170,13 +219,22 @@ func PrintDoc(ctx context.Context, packageName string, val *compiler.Value, form
continue continue
} }
// Package Name + Comment // Field Name + Description
comment := common.ValueDocString(v) comment := common.ValueDocString(v)
switch format { switch format {
case textFormat: case textFormat:
fmt.Printf("%s\n\n%s%s\n", name, textPadding, comment) fmt.Printf("\n%s\n\n%s%s\n", name, textPadding, comment)
case markdownFormat: case markdownFormat:
fmt.Printf("### %s\n\n%s\n\n", name, mdEscape(comment)) fmt.Printf("### %s\n\n", name)
if comment != "-" {
fmt.Printf("%s\n\n", mdEscape(comment))
}
case jsonFormat:
fieldJSON.Name = name
comment := common.ValueDocString(val)
if comment != "" {
fieldJSON.Description = comment
}
} }
// Inputs // Inputs
@ -195,6 +253,8 @@ func PrintDoc(ctx context.Context, packageName string, val *compiler.Value, form
break break
} }
printValuesMarkdown(name, inp) printValuesMarkdown(name, inp)
case jsonFormat:
fieldJSON.Inputs = valuesToJSON(name, inp)
} }
// Outputs // Outputs
@ -213,7 +273,17 @@ func PrintDoc(ctx context.Context, packageName string, val *compiler.Value, form
break break
} }
printValuesMarkdown(name, out) printValuesMarkdown(name, out)
case jsonFormat:
fieldJSON.Outputs = valuesToJSON(name, out)
packageJSON.Fields = append(packageJSON.Fields, fieldJSON)
} }
} }
if format == jsonFormat {
data, err := json.MarshalIndent(packageJSON, "", " ")
if err != nil {
lg.Fatal().Err(err).Msg("json marshal")
}
fmt.Printf("%s\n", data)
}
} }