feat: ramp up docs

davidovich · Feb 27, 2020 · 7597a9d · 7597a9d
1 parent c2997bb
commit 7597a9d
Show file tree

Hide file tree

Showing 3 changed files with 164 additions and 96 deletions.
diff --git a/main.go b/main.go
@@ -2,13 +2,14 @@ package main
 
 import (
 	"flag"
-	"fmt"
 	"io/ioutil"
 	"log"
 	"os"
+	"path/filepath"
 
 	"github.com/jsonnet-libs/k8s/pkg/docs"
 	"github.com/jsonnet-libs/k8s/pkg/model"
+	"github.com/jsonnet-libs/k8s/pkg/render"
 	"github.com/jsonnet-libs/k8s/pkg/swagger"
 )
 
@@ -32,14 +33,49 @@ func main() {
 	}
 
 	groups := model.Load(s)
-	fmt.Println(docs.For("Service", groups["core"]["v1"].Kinds["service"]))
 
-	// for name, group := range groups {
-	// 	o := render.Group(name, group)
+	if err := genDocs(groups, *dir); err != nil {
+		log.Fatalln(err)
+	}
+}
+
+func genDocs(groups map[string]model.Group, dir string) error {
+	for name, grp := range groups {
+
+		path := filepath.Join(dir, name)
+		if err := os.MkdirAll(path, os.ModePerm); err != nil {
+			return err
+		}
+
+		overview := docs.Group(name, grp)
+		if err := ioutil.WriteFile(filepath.Join(path, "README.md"), []byte(overview), 0644); err != nil {
+			return err
+		}
 
-	// 	file := filepath.Join(*dir, name+".libsonnet")
-	// 	if err := ioutil.WriteFile(file, []byte(o.String()), 0644); err != nil {
-	// 		log.Fatalln(err)
-	// 	}
-	// }
+		for verName, ver := range grp {
+			for name, kind := range ver.Kinds {
+				kindMd := docs.Kind(name, kind)
+				if err := ioutil.WriteFile(
+					filepath.Join(path, verName+"."+name+".md"),
+					[]byte(kindMd),
+					0644,
+				); err != nil {
+					return err
+				}
+			}
+		}
+	}
+
+	return nil
+}
+
+func jsonnet(groups map[string]model.Group, dir string) error {
+	for name, group := range groups {
+		o := render.Group(name, group)
+		file := filepath.Join(dir, name+".libsonnet")
+		if err := ioutil.WriteFile(file, []byte(o.String()), 0644); err != nil {
+			return err
+		}
+	}
+	return nil
 }
diff --git a/pkg/docs/docs.go b/pkg/docs/docs.go
@@ -2,104 +2,25 @@ package docs
 
 import (
 	"bytes"
-	"fmt"
-	"sort"
-	"strings"
 	"text/template"
 
 	"github.com/jsonnet-libs/k8s/pkg/model"
 )
 
-var tmpl = template.Must(template.New("").Parse(`
-## {{.Name}}
-{{.Help}}
+var overviewTmpl = template.Must(template.New("").Parse(`
+{{ range $v, $ver := . }}
+#### {{ .ApiVersion }}
 
-**Functions:**
-{{ range .Funcs }}
-[` + "`fn {{.Name}}`" + `](#{{.HtmlID}})  {{ end }}
+{{ range $name, $k :=  .Kinds }}
+[` + "`{{ $name }}`" + `]({{$v}}.{{$name}}.md)  {{ end }}
 
----
-
-{{ range .Funcs }}
-### ` + "`fn {{ .Name }}`" + `
-{{ .Help }}
-` + "```jsonnet" + `
-{
-  {{ .Signature }}
-}
-` + "```" + `
 {{ end }}
 `))
 
-type Documentable struct {
-	Name string
-	Help string
-
-	Funcs []Func
-}
-
-type Func struct {
-	Name   string
-	HtmlID string
-
-	Help      string
-	Signature string
-}
-
-// For returns markdown docs for the given kind.
-func For(name string, kind model.Kind) string {
-	d := Documentable{
-		Name: name,
-		Help: kind.Help,
-		Funcs: []Func{{
-			Name:      "new",
-			HtmlID:    "fn-new",
-			Help:      kind.New.Help,
-			Signature: signature("new", kind.New.Args, "{}"),
-		}},
-	}
-
-	funcs := modifiers(kind.Modifiers)
-	sort.SliceStable(funcs, func(i, j int) bool {
-		return funcs[i].Name < funcs[j].Name
-	})
-	d.Funcs = append(d.Funcs, funcs...)
-
-	buf := bytes.Buffer{}
-	if err := tmpl.Execute(&buf, d); err != nil {
+func Group(name string, group model.Group) string {
+	var buf bytes.Buffer
+	if err := overviewTmpl.Execute(&buf, group); err != nil {
 		panic(err)
 	}
 	return buf.String()
 }
-
-func modifiers(mods map[string]interface{}, prefix ...string) (funcs []Func) {
-	for name, v := range mods {
-		switch m := v.(type) {
-		case model.Object:
-			funcs = append(funcs, modifiers(m.Fields, append(prefix, name)...)...)
-			break
-		case model.Modifier:
-			n := fmt.Sprintf("%s.%s", strings.Join(prefix, "."), name)
-			funcs = append(funcs, Func{
-				Name:   n,
-				HtmlID: fmt.Sprintf("fn-%s", strings.ToLower(strings.Replace(n, ".", "", -1))),
-				Help:   m.Help,
-				Signature: signature(
-					name,
-					[]model.Parameter{m.Arg},
-					"{}",
-				),
-			})
-		}
-	}
-	return funcs
-}
-
-func signature(name string, args []model.Parameter, returns string) string {
-	strArgs := make([]string, len(args))
-	for i, a := range args {
-		strArgs[i] = a.String()
-	}
-
-	return fmt.Sprintf("%s(%s):: %s", name, strings.Join(strArgs, ", "), returns)
-}
diff --git a/pkg/docs/kind.go b/pkg/docs/kind.go
@@ -0,0 +1,111 @@
+package docs
+
+import (
+	"bytes"
+	"fmt"
+	"sort"
+	"strings"
+	"text/template"
+
+	"github.com/jsonnet-libs/k8s/pkg/model"
+)
+
+var kindTmpl = template.Must(template.New("").Parse(`
+## {{.Name}}
+{{.Help}}
+
+**Functions:**
+{{ range .Funcs }}
+[` + "`fn {{.Name}}`" + `](#{{.HtmlID}})  {{ end }}
+
+---
+
+{{ range .Funcs }}
+### ` + "`fn {{ .Name }}`" + `
+{{ .Help }}
+` + "```jsonnet" + `
+{
+  {{ .Signature }}
+}
+` + "```" + `
+{{ end }}
+`))
+
+type Documentable struct {
+	Name string
+	Help string
+
+	Funcs []Func
+}
+
+type Func struct {
+	Name   string
+	HtmlID string
+
+	Help      string
+	Signature string
+}
+
+// Kind returns markdown docs for the given kind.
+func Kind(name string, kind model.Kind) string {
+	d := Documentable{
+		Name:  name,
+		Help:  kind.Help,
+		Funcs: []Func{},
+	}
+
+	if kind.New != nil {
+		d.Funcs = append(d.Funcs,
+			Func{
+				Name:      "new",
+				HtmlID:    "fn-new",
+				Help:      kind.New.Help,
+				Signature: signature("new", kind.New.Args, "{}"),
+			},
+		)
+	}
+
+	funcs := modifiers(kind.Modifiers)
+	sort.SliceStable(funcs, func(i, j int) bool {
+		return funcs[i].Name < funcs[j].Name
+	})
+	d.Funcs = append(d.Funcs, funcs...)
+
+	buf := bytes.Buffer{}
+	if err := kindTmpl.Execute(&buf, d); err != nil {
+		panic(err)
+	}
+	return buf.String()
+}
+
+func modifiers(mods map[string]interface{}, prefix ...string) (funcs []Func) {
+	for name, v := range mods {
+		switch m := v.(type) {
+		case model.Object:
+			funcs = append(funcs, modifiers(m.Fields, append(prefix, name)...)...)
+			break
+		case model.Modifier:
+			n := fmt.Sprintf("%s.%s", strings.Join(prefix, "."), name)
+			funcs = append(funcs, Func{
+				Name:   n,
+				HtmlID: fmt.Sprintf("fn-%s", strings.ToLower(strings.Replace(n, ".", "", -1))),
+				Help:   m.Help,
+				Signature: signature(
+					name,
+					[]model.Parameter{m.Arg},
+					"{}",
+				),
+			})
+		}
+	}
+	return funcs
+}
+
+func signature(name string, args []model.Parameter, returns string) string {
+	strArgs := make([]string, len(args))
+	for i, a := range args {
+		strArgs[i] = a.String()
+	}
+
+	return fmt.Sprintf("%s(%s):: %s", name, strings.Join(strArgs, ", "), returns)
+}