mirror of
https://github.com/TECHNOFAB11/docsonnet.git
synced 2025-12-11 22:10:13 +01:00
feat: subpackage rendering
This commit is contained in:
sh0rez
parent
09e8e3ddd9
commit
6e95ea768a
7 changed files with 306 additions and 203 deletions
207
main.go
207
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"`
|
||||
}
|
||||
|
|
|
|||
76
pkg/docsonnet/field.go
Normal file
76
pkg/docsonnet/field.go
Normal file
|
|
@ -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
|
||||
}
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
package main
|
||||
package docsonnet
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
78
pkg/docsonnet/load.go
Normal file
78
pkg/docsonnet/load.go
Normal file
|
|
@ -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)
|
||||
}
|
||||
58
pkg/docsonnet/model.go
Normal file
58
pkg/docsonnet/model.go
Normal file
|
|
@ -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"
|
||||
)
|
||||
34
pkg/render/paths.go
Normal file
34
pkg/render/paths.go
Normal file
|
|
@ -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
|
||||
}
|
||||
|
|
@ -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
|
||||
elems = append(elems,
|
||||
md.Headline(2, "Index"),
|
||||
md.List(mdIndex(pkg.API, "", slug.New())...),
|
||||
)
|
||||
// subpackages
|
||||
if len(pkg.Sub) > 0 {
|
||||
elems = append(elems, md.Headline(2, "Subpackages"))
|
||||
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
|
||||
elems = append(elems, md.Headline(2, "Fields"))
|
||||
elems = append(elems, mdApi(pkg.API, "")...)
|
||||
// fields of this package
|
||||
if len(pkg.API) > 0 {
|
||||
// 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue