feat: ignore

Implements ignoring certain keys right in Jsonnet, by adding:

  {
    '#foo': "ignore",
    foo: {}
  }

This is especially useful for objects that include `self` references,
which might otherwise recurse infinitely

pkg/docsonnet/fast.go

@@ -11,7 +11,7 @@ import (
 // Data assumptions:
 // - only map[string]interface{} and fields
 // - fields (#...) coming first
-func fastLoad(d DS) Package {
+func fastLoad(d ds) Package {
 	pkg := d.Package()
 
 	pkg.API = make(Fields)
@@ -34,7 +34,7 @@ func fastLoad(d DS) Package {
 		// non-docsonnet
 		// subpackage?
 		if _, ok := f["#"]; ok {
-			p := fastLoad(DS(f))
+			p := fastLoad(ds(f))
 			pkg.Sub[p.Name] = p
 			continue
 		}
@@ -94,7 +94,7 @@ func loadField(name string, field map[string]interface{}, parent map[string]inte
 		return loadObj(name, iobj.(map[string]interface{}), parent)
 	}
 
-	panic("field lacking {function | object}")
+	panic(fmt.Sprintf("field %s lacking {function | object}", name))
 }
 
 func loadFn(name string, msi map[string]interface{}) Field {
@@ -161,9 +161,9 @@ func loadObj(name string, msi map[string]interface{}, parent map[string]interfac
 	return Field{Object: &obj}
 }
 
-type DS map[string]interface{}
+type ds map[string]interface{}
 
-func (d DS) Package() Package {
+func (d ds) Package() Package {
 	hash, ok := d["#"]
 	if !ok {
 		log.Fatalln("Package declaration missing")

pkg/docsonnet/load.go

@@ -10,8 +10,22 @@ import (
 	"github.com/markbates/pkger"
 )
 
-// Load extracts docsonnet data from the given Jsonnet document
+// 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)
+	if err != nil {
+		return nil, err
+	}
+
+	return Transform([]byte(data))
+}
+
+// Extract parses the Jsonnet file at `filename`, extracting all docsonnet related
+// 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) {
 	// get load.libsonnet from embedded data
 	file, err := pkger.Open("/load.libsonnet")
 	if err != nil {
@@ -33,15 +47,18 @@ func Load(filename string) (*Package, error) {
 	// invoke load.libsonnet
 	vm.ExtCode("main", fmt.Sprintf(`(import "%s")`, filename))
 
-	log.Println("Evaluating Jsonnet")
 	data, err := vm.EvaluateSnippet("load.libsonnet", string(load))
 	if err != nil {
 		return nil, err
 	}
 
-	log.Println("Transforming result")
-	// parse the result
-	var d DS
+	return []byte(data), nil
+}
+
+// Transform converts the raw result of `Extract` to the actual docsonnet object
+// model `*docsonnet.Package`.
+func Transform(data []byte) (*Package, error) {
+	var d ds
 	if err := json.Unmarshal([]byte(data), &d); err != nil {
 		log.Fatalln(err)
 	}

pkg/render/fs.go

@@ -2,31 +2,26 @@ package render
 
 import (
 	"io/ioutil"
-	"log"
 	"os"
 	"path/filepath"
 
 	"github.com/sh0rez/docsonnet/pkg/docsonnet"
 )
 
-func To(api, out string) error {
-	pkg, err := docsonnet.Load(api)
-	if err != nil {
-		return err
+func To(pkg docsonnet.Package, dir string, opts Opts) (int, error) {
+	if err := os.MkdirAll(dir, os.ModePerm); err != nil {
+		return 0, err
 	}
 
-	if err := os.MkdirAll(out, os.ModePerm); err != nil {
-		return err
-	}
+	data := Render(pkg, opts)
 
-	log.Println("Rendering .md files")
-	data := Render(*pkg)
+	n := 0
 	for k, v := range data {
-		if err := ioutil.WriteFile(filepath.Join(out, k), []byte(v), 0644); err != nil {
-			return err
+		if err := ioutil.WriteFile(filepath.Join(dir, k), []byte(v), 0644); err != nil {
+			return n, err
 		}
+		n++
 	}
 
-	log.Printf("Success! Rendered %v packages from '%s' to '%s'", len(data), api, out)
-	return nil
+	return n, nil
 }

pkg/render/render.go

@@ -2,6 +2,7 @@ package render
 
 import (
 	"fmt"
+	"path"
 	"sort"
 	"strings"
 
@@ -10,14 +11,18 @@ import (
 	"github.com/sh0rez/docsonnet/pkg/slug"
 )
 
-func Render(pkg docsonnet.Package) map[string]string {
-	return render(pkg, nil, true)
+type Opts struct {
+	URLPrefix string
 }
 
-func render(pkg docsonnet.Package, parents []string, root bool) map[string]string {
-	link := "/" + strings.Join(append(parents, pkg.Name), "/")
+func Render(pkg docsonnet.Package, opts Opts) map[string]string {
+	return render(pkg, nil, true, opts.URLPrefix)
+}
+
+func render(pkg docsonnet.Package, parents []string, root bool, urlPrefix string) map[string]string {
+	link := path.Join("/", urlPrefix, strings.Join(append(parents, pkg.Name), "/"))
 	if root {
-		link = "/"
+		link = path.Join("/", urlPrefix)
 	}
 
 	// head
@@ -83,7 +88,7 @@ func render(pkg docsonnet.Package, parents []string, root bool) map[string]strin
 			if root {
 				path = parents
 			}
-			got := render(s, path, false)
+			got := render(s, path, false, urlPrefix)
 			for k, v := range got {
 				out[k] = v
 			}