feat: document plain values (#12)

* feat: document plain values

Adds `d.val` to attach type and help information to plain Jsonnet
values, apart from specially treated `fn` and `obj`.

* feat: defaults

pkg/docsonnet/fast.go

@@ -94,7 +94,32 @@ func loadField(name string, field map[string]interface{}, parent map[string]inte
 		return loadObj(name, iobj.(map[string]interface{}), parent)
 	}
 
-	panic(fmt.Sprintf("field %s lacking {function | object}", name))
+	if vobj, ok := field["value"]; ok {
+		return loadValue(name, vobj.(map[string]interface{}))
+	}
+
+	panic(fmt.Sprintf("field %s lacking {function | object | value}", name))
+}
+
+func loadValue(name string, msi map[string]interface{}) Field {
+	h, ok := msi["help"].(string)
+	if !ok {
+		h = ""
+	}
+
+	t, ok := msi["type"].(string)
+	if !ok {
+		panic(fmt.Sprintf("value %s lacking type information", name))
+	}
+
+	v := Value{
+		Name:    name,
+		Help:    h,
+		Type:    Type(t),
+		Default: msi["default"],
+	}
+
+	return Field{Value: &v}
 }
 
 func loadFn(name string, msi map[string]interface{}) Field {

pkg/docsonnet/load.go

@@ -10,10 +10,14 @@ import (
 	"github.com/markbates/pkger"
 )
 
+type Opts struct {
+	JPath []string
+}
+
 // Load extracts and transforms the docsonnet data in `filename`, returning the
 // top level docsonnet package.
-func Load(filename string) (*Package, error) {
-	data, err := Extract(filename)
+func Load(filename string, opts Opts) (*Package, error) {
+	data, err := Extract(filename, opts)
 	if err != nil {
 		return nil, err
 	}
@@ -25,7 +29,7 @@ func Load(filename string) (*Package, error) {
 // information, exactly as they appear in Jsonnet. Keep in mind this
 // representation is usually not suitable for any use, use `Transform` to
 // convert it to the familiar docsonnet data model.
-func Extract(filename string) ([]byte, error) {
+func Extract(filename string, opts Opts) ([]byte, error) {
 	// get load.libsonnet from embedded data
 	file, err := pkger.Open("/load.libsonnet")
 	if err != nil {
@@ -38,7 +42,7 @@ func Extract(filename string) ([]byte, error) {
 
 	// setup Jsonnet vm
 	vm := jsonnet.MakeVM()
-	importer, err := newImporter()
+	importer, err := newImporter(opts.JPath)
 	if err != nil {
 		return nil, err
 	}
@@ -74,7 +78,7 @@ type importer struct {
 	util jsonnet.Contents
 }
 
-func newImporter() (*importer, error) {
+func newImporter(paths []string) (*importer, error) {
 	file, err := pkger.Open("/doc-util/main.libsonnet")
 	if err != nil {
 		return nil, err
@@ -85,7 +89,7 @@ func newImporter() (*importer, error) {
 	}
 
 	return &importer{
-		fi:   jsonnet.FileImporter{},
+		fi:   jsonnet.FileImporter{JPaths: paths},
 		util: jsonnet.MakeContents(string(load)),
 	}, nil
 }

pkg/docsonnet/model.go

@@ -41,7 +41,8 @@ type Value struct {
 	Name string `json:"-"`
 	Help string `json:"help"`
 
-	Type Type `json:"type"`
+	Type    Type        `json:"type"`
+	Default interface{} `json:"default"`
 }
 
 // Type is a Jsonnet type

pkg/render/render.go

@@ -119,6 +119,11 @@ func renderIndex(api docsonnet.Fields, path string, s *slug.Slugger) []md.Elem {
 			link := "#" + s.Slug("obj "+path+obj.Name)
 			elems = append(elems, md.Link(md.Code(name), link))
 			elems = append(elems, md.List(renderIndex(obj.Fields, path+obj.Name+".", s)...))
+		case v.Value != nil:
+			val := v.Value
+			name := md.Text(fmt.Sprintf("%s %s%s", val.Type, path, val.Name))
+			link := "#" + s.Slug(name.String())
+			elems = append(elems, md.Link(md.Code(name), link))
 		}
 	}
 	return elems
@@ -144,6 +149,23 @@ func renderApi(api docsonnet.Fields, path string) []md.Elem {
 				md.Text(obj.Help),
 			)
 			elems = append(elems, renderApi(obj.Fields, path+obj.Name+".")...)
+
+		case v.Value != nil:
+			val := v.Value
+			elems = append(elems,
+				md.Headline(3, fmt.Sprintf("%s %s%s", val.Type, path, val.Name)),
+			)
+
+			if val.Default != nil {
+				elems = append(elems, md.Paragraph(
+					md.Italic(md.Text("Default value: ")),
+					md.Code(md.Text(fmt.Sprint(val.Default))),
+				))
+			}
+
+			elems = append(elems,
+				md.Text(val.Help),
+			)
 		}
 	}