feat: subpackage rendering

main.go

@@ -2,26 +2,21 @@ package main
 
 import (
 	"encoding/json"
-	"errors"
 	"fmt"
 	"io/ioutil"
 	"log"
+	"os"
+	"path/filepath"
 
 	"github.com/go-clix/cli"
-	"github.com/google/go-jsonnet"
+
-	"github.com/markbates/pkger"
+	"github.com/sh0rez/docsonnet/pkg/docsonnet"
+	"github.com/sh0rez/docsonnet/pkg/render"
 )
 
-type Package struct {
-	Name   string `json:"name"`
-	Import string `json:"import"`
-	Help   string `json:"help"`
-
-	API Fields             `json:"api,omitempty"`
-	Sub map[string]Package `json:"sub,omitempty"`
-}
-
 func main() {
+	log.SetFlags(0)
+
 	root := &cli.Command{
 		Use:   "docsonnet",
 		Short: "Utility to parse and transform Jsonnet code that uses the docsonnet extension",
@@ -42,7 +37,7 @@ func loadCmd() *cli.Command {
 	}
 
 	cmd.Run = func(cmd *cli.Command, args []string) error {
-		pkg, err := Load(args[0])
+		pkg, err := docsonnet.Load(args[0])
 		if err != nil {
 			return err
 		}
@@ -65,184 +60,28 @@ func renderCmd() *cli.Command {
 		Args:  cli.ArgsExact(1),
 	}
 
+	output := cmd.Flags().StringP("output", "o", "docs", "directory to write the .md files to")
+
 	cmd.Run = func(cmd *cli.Command, args []string) error {
-		pkg, err := Load(args[0])
+		pkg, err := docsonnet.Load(args[0])
 		if err != nil {
 			return err
 		}
 
-		fmt.Println(render(*pkg))
+		for path, pkg := range render.Paths(*pkg) {
+			to := filepath.Join(*output, path)
+			if err := os.MkdirAll(filepath.Dir(to), os.ModePerm); err != nil {
+				return err
+			}
+
+			data := render.Render(pkg)
+			if err := ioutil.WriteFile(to, []byte(data), 0644); err != nil {
+				return err
+			}
+		}
+
 		return nil
 	}
 
 	return cmd
 }
-
-func Load(filename string) (*Package, error) {
-	file, err := pkger.Open("/load.libsonnet")
-	if err != nil {
-		return nil, err
-	}
-	load, err := ioutil.ReadAll(file)
-	if err != nil {
-		return nil, err
-	}
-
-	vm := jsonnet.MakeVM()
-	importer, err := newImporter()
-	if err != nil {
-		return nil, err
-	}
-	vm.Importer(importer)
-
-	vm.ExtCode("main", fmt.Sprintf(`(import "%s")`, filename))
-	data, err := vm.EvaluateSnippet("load.libsonnet", string(load))
-	if err != nil {
-		return nil, err
-	}
-
-	var d Package
-	if err := json.Unmarshal([]byte(data), &d); err != nil {
-		log.Fatalln(err)
-	}
-
-	return &d, nil
-}
-
-type Importer struct {
-	fi   jsonnet.FileImporter
-	util jsonnet.Contents
-}
-
-func newImporter() (*Importer, error) {
-	file, err := pkger.Open("/doc-util/main.libsonnet")
-	if err != nil {
-		return nil, err
-	}
-	load, err := ioutil.ReadAll(file)
-	if err != nil {
-		return nil, err
-	}
-
-	return &Importer{
-		fi:   jsonnet.FileImporter{},
-		util: jsonnet.MakeContents(string(load)),
-	}, nil
-}
-
-func (i *Importer) Import(importedFrom, importedPath string) (contents jsonnet.Contents, foundAt string, err error) {
-	if importedPath == "doc-util/main.libsonnet" {
-		return i.util, "<internal>", nil
-	}
-
-	return i.fi.Import(importedFrom, importedPath)
-}
-
-type Object struct {
-	Name string `json:"-"`
-	Help string `json:"help"`
-
-	// children
-	Fields Fields `json:"fields"`
-}
-
-type Fields map[string]Field
-
-func (fPtr *Fields) UnmarshalJSON(data []byte) error {
-	if *fPtr == nil {
-		*fPtr = make(Fields)
-	}
-	f := *fPtr
-
-	tmp := make(map[string]Field)
-	if err := json.Unmarshal(data, &tmp); err != nil {
-		return err
-	}
-
-	for k, v := range tmp {
-		switch {
-		case v.Function != nil:
-			v.Function.Name = k
-		case v.Object != nil:
-			v.Object.Name = k
-		case v.Value != nil:
-			v.Value.Name = k
-		}
-		f[k] = v
-	}
-
-	return nil
-}
-
-// Field represents any field of an object.
-type Field struct {
-	// Function value
-	Function *Function `json:"function,omitempty"`
-	// Object value
-	Object *Object `json:"object,omitempty"`
-	// Any other value
-	Value *Value `json:"value,omitempty"`
-}
-
-func (o *Field) UnmarshalJSON(data []byte) error {
-	type fake Field
-
-	var f fake
-	if err := json.Unmarshal(data, &f); err != nil {
-		return err
-	}
-
-	switch {
-	case f.Function != nil:
-		o.Function = f.Function
-	case f.Object != nil:
-		o.Object = f.Object
-	case f.Value != nil:
-		o.Value = f.Value
-	default:
-		return errors.New("field has no value")
-	}
-
-	return nil
-}
-
-func (o Field) MarshalJSON() ([]byte, error) {
-	if o.Function == nil && o.Object == nil && o.Value == nil {
-		return nil, errors.New("field has no value")
-	}
-
-	type fake Field
-	return json.Marshal(fake(o))
-}
-
-type Function struct {
-	Name string `json:"-"`
-	Help string `json:"help"`
-
-	Args []Argument `json:"args,omitempty"`
-}
-
-type Type string
-
-const (
-	TypeString = "string"
-	TypeNumber = "number"
-	TypeBool   = "boolean"
-	TypeObject = "object"
-	TypeArray  = "array"
-	TypeAny    = "any"
-	TypeFunc   = "function"
-)
-
-type Value struct {
-	Name string `json:"-"`
-	Help string `json:"help"`
-
-	Type Type `json:"type"`
-}
-
-type Argument struct {
-	Type    Type        `json:"type"`
-	Name    string      `json:"name"`
-	Default interface{} `json:"default"`
-}

pkg/docsonnet/field.go

@@ -0,0 +1,76 @@
+package docsonnet
+
+import (
+	"encoding/json"
+	"errors"
+)
+
+// Field represents any field of an object.
+type Field struct {
+	// Function value
+	Function *Function `json:"function,omitempty"`
+	// Object value
+	Object *Object `json:"object,omitempty"`
+	// Any other value
+	Value *Value `json:"value,omitempty"`
+}
+
+func (o *Field) UnmarshalJSON(data []byte) error {
+	type fake Field
+
+	var f fake
+	if err := json.Unmarshal(data, &f); err != nil {
+		return err
+	}
+
+	switch {
+	case f.Function != nil:
+		o.Function = f.Function
+	case f.Object != nil:
+		o.Object = f.Object
+	case f.Value != nil:
+		o.Value = f.Value
+	default:
+		return errors.New("field has no value")
+	}
+
+	return nil
+}
+
+func (o Field) MarshalJSON() ([]byte, error) {
+	if o.Function == nil && o.Object == nil && o.Value == nil {
+		return nil, errors.New("field has no value")
+	}
+
+	type fake Field
+	return json.Marshal(fake(o))
+}
+
+// Fields is a list of fields
+type Fields map[string]Field
+
+func (fPtr *Fields) UnmarshalJSON(data []byte) error {
+	if *fPtr == nil {
+		*fPtr = make(Fields)
+	}
+	f := *fPtr
+
+	tmp := make(map[string]Field)
+	if err := json.Unmarshal(data, &tmp); err != nil {
+		return err
+	}
+
+	for k, v := range tmp {
+		switch {
+		case v.Function != nil:
+			v.Function.Name = k
+		case v.Object != nil:
+			v.Object.Name = k
+		case v.Value != nil:
+			v.Value.Name = k
+		}
+		f[k] = v
+	}
+
+	return nil
+}

pkg/docsonnet/field_test.go

@@ -1,4 +1,4 @@
-package main
+package docsonnet
 
 import (
 	"encoding/json"

pkg/docsonnet/load.go

@@ -0,0 +1,78 @@
+package docsonnet
+
+import (
+	"encoding/json"
+	"fmt"
+	"io/ioutil"
+	"log"
+
+	"github.com/google/go-jsonnet"
+	"github.com/markbates/pkger"
+)
+
+// Load extracts docsonnet data from the given Jsonnet document
+func Load(filename string) (*Package, error) {
+	// get load.libsonnet from embedded data
+	file, err := pkger.Open("/load.libsonnet")
+	if err != nil {
+		return nil, err
+	}
+	load, err := ioutil.ReadAll(file)
+	if err != nil {
+		return nil, err
+	}
+
+	// setup Jsonnet vm
+	vm := jsonnet.MakeVM()
+	importer, err := newImporter()
+	if err != nil {
+		return nil, err
+	}
+	vm.Importer(importer)
+
+	// invoke load.libsonnet
+	vm.ExtCode("main", fmt.Sprintf(`(import "%s")`, filename))
+	data, err := vm.EvaluateSnippet("load.libsonnet", string(load))
+	if err != nil {
+		return nil, err
+	}
+
+	// parse the result
+	var d Package
+	if err := json.Unmarshal([]byte(data), &d); err != nil {
+		log.Fatalln(err)
+	}
+
+	return &d, nil
+}
+
+// importer wraps jsonnet.FileImporter, to statically provide load.libsonnet,
+// bundled with the binary
+type importer struct {
+	fi   jsonnet.FileImporter
+	util jsonnet.Contents
+}
+
+func newImporter() (*importer, error) {
+	file, err := pkger.Open("/doc-util/main.libsonnet")
+	if err != nil {
+		return nil, err
+	}
+	load, err := ioutil.ReadAll(file)
+	if err != nil {
+		return nil, err
+	}
+
+	return &importer{
+		fi:   jsonnet.FileImporter{},
+		util: jsonnet.MakeContents(string(load)),
+	}, nil
+}
+
+func (i *importer) Import(importedFrom, importedPath string) (contents jsonnet.Contents, foundAt string, err error) {
+	if importedPath == "doc-util/main.libsonnet" {
+		return i.util, "<internal>", nil
+	}
+
+	return i.fi.Import(importedFrom, importedPath)
+}

pkg/docsonnet/model.go

@@ -0,0 +1,58 @@
+package docsonnet
+
+// Package represents a Jsonnet package, having an API (list of Fields) and
+// perhaps subpackages
+type Package struct {
+	Name   string `json:"name"`
+	Import string `json:"import"`
+	Help   string `json:"help"`
+
+	API Fields             `json:"api,omitempty"`
+	Sub map[string]Package `json:"sub,omitempty"`
+}
+
+// Object represents a Jsonnet object, a list of key-value fields
+type Object struct {
+	Name string `json:"-"`
+	Help string `json:"help"`
+
+	// children
+	Fields Fields `json:"fields"`
+}
+
+// Function represents a Jsonnet function, a named construct that takes
+// arguments
+type Function struct {
+	Name string `json:"-"`
+	Help string `json:"help"`
+
+	Args []Argument `json:"args,omitempty"`
+}
+
+// Argument is a function argument, optionally also having a default value
+type Argument struct {
+	Type    Type        `json:"type"`
+	Name    string      `json:"name"`
+	Default interface{} `json:"default"`
+}
+
+// Value is a value of any other type than the special Object and Function types
+type Value struct {
+	Name string `json:"-"`
+	Help string `json:"help"`
+
+	Type Type `json:"type"`
+}
+
+// Type is a Jsonnet type
+type Type string
+
+const (
+	TypeString = "string"
+	TypeNumber = "number"
+	TypeBool   = "boolean"
+	TypeObject = "object"
+	TypeArray  = "array"
+	TypeAny    = "any"
+	TypeFunc   = "function"
+)

pkg/render/paths.go

@@ -0,0 +1,34 @@
+package render
+
+import (
+	"strings"
+
+	"github.com/sh0rez/docsonnet/pkg/docsonnet"
+)
+
+func Paths(pkg docsonnet.Package) map[string]docsonnet.Package {
+	p := paths(pkg)
+	for k, v := range p {
+		delete(p, k)
+		k = strings.TrimPrefix(k, pkg.Name+"/")
+		p[k] = v
+	}
+	return p
+}
+
+func paths(pkg docsonnet.Package) map[string]docsonnet.Package {
+	pkgs := make(map[string]docsonnet.Package)
+	pkgs[pkg.Name+".md"] = pkg
+
+	if len(pkg.Sub) == 0 {
+		return pkgs
+	}
+
+	for _, sub := range pkg.Sub {
+		for k, v := range paths(sub) {
+			pkgs[pkg.Name+"/"+k] = v
+		}
+	}
+
+	return pkgs
+}

pkg/render/render.go

@@ -1,15 +1,16 @@
-package main
+package render
 
 import (
 	"fmt"
 	"sort"
 	"strings"
 
+	"github.com/sh0rez/docsonnet/pkg/docsonnet"
 	"github.com/sh0rez/docsonnet/pkg/md"
 	"github.com/sh0rez/docsonnet/pkg/slug"
 )
 
-func render(pkg Package) string {
+func Render(pkg docsonnet.Package) string {
 	// head
 	elems := []md.Elem{
 		md.Headline(1, "package "+pkg.Name),
@@ -17,27 +18,44 @@ func render(pkg Package) string {
 		md.Text(pkg.Help),
 	}
 
-	// index
+	// subpackages
-	elems = append(elems,
+	if len(pkg.Sub) > 0 {
-		md.Headline(2, "Index"),
+		elems = append(elems, md.Headline(2, "Subpackages"))
-		md.List(mdIndex(pkg.API, "", slug.New())...),
+		var items []md.Elem
-	)
+		for k := range Paths(pkg) {
+			name := strings.TrimSuffix(k, ".md")
+			if name == pkg.Name {
+				continue
+			}
+			items = append(items, md.Link(md.Text(name), k))
+		}
+		elems = append(elems, md.List(items...))
+	}
 
-	// api
+	// fields of this package
-	elems = append(elems, md.Headline(2, "Fields"))
+	if len(pkg.API) > 0 {
-	elems = append(elems, mdApi(pkg.API, "")...)
+		// index
+		elems = append(elems,
+			md.Headline(2, "Index"),
+			md.List(renderIndex(pkg.API, "", slug.New())...),
+		)
+
+		// api
+		elems = append(elems, md.Headline(2, "Fields"))
+		elems = append(elems, renderApi(pkg.API, "")...)
+	}
 
 	return md.Doc(elems...).String()
 }
 
-func mdIndex(api Fields, path string, s *slug.Slugger) []md.Elem {
+func renderIndex(api docsonnet.Fields, path string, s *slug.Slugger) []md.Elem {
 	var elems []md.Elem
 	for _, k := range sortFields(api) {
 		v := api[k]
 		switch {
 		case v.Function != nil:
 			fn := v.Function
-			name := md.Text(fmt.Sprintf("fn %s(%s)", fn.Name, params(fn.Args)))
+			name := md.Text(fmt.Sprintf("fn %s(%s)", fn.Name, renderParams(fn.Args)))
 			link := "#" + s.Slug("fn "+path+fn.Name)
 			elems = append(elems, md.Link(md.Code(name), link))
 		case v.Object != nil:
@@ -45,13 +63,13 @@ func mdIndex(api Fields, path string, s *slug.Slugger) []md.Elem {
 			name := md.Text("obj " + path + obj.Name)
 			link := "#" + s.Slug("obj "+path+obj.Name)
 			elems = append(elems, md.Link(md.Code(name), link))
-			elems = append(elems, md.List(mdIndex(obj.Fields, path+obj.Name+".", s)...))
+			elems = append(elems, md.List(renderIndex(obj.Fields, path+obj.Name+".", s)...))
 		}
 	}
 	return elems
 }
 
-func mdApi(api Fields, path string) []md.Elem {
+func renderApi(api docsonnet.Fields, path string) []md.Elem {
 	var elems []md.Elem
 
 	for _, k := range sortFields(api) {
@@ -61,7 +79,7 @@ func mdApi(api Fields, path string) []md.Elem {
 			fn := v.Function
 			elems = append(elems,
 				md.Headline(3, fmt.Sprintf("fn %s%s", path, fn.Name)),
-				md.CodeBlock("ts", fmt.Sprintf("%s(%s)", fn.Name, params(fn.Args))),
+				md.CodeBlock("ts", fmt.Sprintf("%s(%s)", fn.Name, renderParams(fn.Args))),
 				md.Text(fn.Help),
 			)
 		case v.Object != nil:
@@ -70,14 +88,14 @@ func mdApi(api Fields, path string) []md.Elem {
 				md.Headline(2, fmt.Sprintf("obj %s%s", path, obj.Name)),
 				md.Text(obj.Help),
 			)
-			elems = append(elems, mdApi(obj.Fields, path+obj.Name+".")...)
+			elems = append(elems, renderApi(obj.Fields, path+obj.Name+".")...)
 		}
 	}
 
 	return elems
 }
 
-func sortFields(api Fields) []string {
+func sortFields(api docsonnet.Fields) []string {
 	keys := make([]string, len(api))
 	for k := range api {
 		keys = append(keys, k)
@@ -97,7 +115,7 @@ func sortFields(api Fields) []string {
 	return keys
 }
 
-func params(a []Argument) string {
+func renderParams(a []docsonnet.Argument) string {
 	args := make([]string, 0, len(a))
 	for _, a := range a {
 		arg := a.Name