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

load.libsonnet

@@ -12,6 +12,8 @@ local lib = {
     local aux(old, key) =
       if !std.isObject(pkg[key]) then
         old
+      else if std.objectHasAll(pkg, '#' + key) && pkg['#' + key] == 'ignore' then
+        old
       else if std.startsWith(key, '#') then
         old { [key]: pkg[key] }
       else if self.scan(pkg[key]) then
@@ -21,4 +23,5 @@ local lib = {
     std.foldl(aux, std.objectFieldsAll(pkg), {}),
 };
 
+
 lib.load(std.extVar('main'))

main.go

@@ -15,33 +15,52 @@ func main() {
 	log.SetFlags(0)
 
 	root := &cli.Command{
-		Use:   "docsonnet",
+		Use:   "docsonnet <file>",
 		Short: "Utility to parse and transform Jsonnet code that uses the docsonnet extension",
+		Args:  cli.ArgsExact(1),
 	}
 
 	dir := root.Flags().StringP("output", "o", "docs", "directory to write the .md files to")
-	outputMd := root.Flags().Bool("md", true, "render as markdown files")
 	outputJSON := root.Flags().Bool("json", false, "print loaded docsonnet as JSON")
+	outputRaw := root.Flags().Bool("raw", false, "don't transform, dump raw eval result")
+	urlPrefix := root.Flags().String("urlPrefix", "/", "url-prefix for frontmatter")
 
 	root.Run = func(cmd *cli.Command, args []string) error {
 		file := args[0]
 
-		switch {
-		case *outputJSON:
-			model, err := docsonnet.Load(file)
-			if err != nil {
-				return err
-			}
-			data, err := json.MarshalIndent(model, "", "  ")
+		log.Println("Extracting from Jsonnet")
+		data, err := docsonnet.Extract(file)
+		if err != nil {
+			log.Fatalln("Extracting:", err)
+		}
+		if *outputRaw {
+			fmt.Println(string(data))
+			return nil
+		}
+
+		log.Println("Transforming to docsonnet model")
+		pkg, err := docsonnet.Transform(data)
+		if err != nil {
+			log.Fatalln("Transforming:", err)
+		}
+		if *outputJSON {
+			data, err := json.MarshalIndent(pkg, "", "  ")
 			if err != nil {
 				return err
 			}
-
 			fmt.Println(string(data))
-		case *outputMd:
-			return render.To(file, *dir)
+			return nil
+		}
+
+		log.Println("Rendering markdown")
+		n, err := render.To(*pkg, *dir, render.Opts{
+			URLPrefix: *urlPrefix,
+		})
+		if err != nil {
+			log.Fatalln("Rendering:", err)
 		}
 
+		log.Printf("Success! Rendered %v packages from '%s' to '%s'", n, file, *dir)
 		return nil
 	}
 

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
 			}