Add markdown format to docgen

Author: antonmedv

docgen/README.md

@@ -0,0 +1,48 @@
+# DocGen
+
+This package provides documentation generator with JSON or Markdown output.
+
+## Usage
+
+Create a file and put next code into it. 
+
+```go
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+  
+	"github.com/antonmedv/expr/docgen"
+)
+
+func main() {
+	// TODO: Replace env with your own types.
+	doc := docgen.CreateDoc(env)
+  
+	buf, err := json.MarshalIndent(doc, "", "  ")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(string(buf))
+}
+```
+
+Run `go run your_file.go`. Documentation will be printed in JSON format.
+
+## Markdown
+
+To generate markdown documentation: 
+
+```go
+package main
+
+import "github.com/antonmedv/expr/docgen"
+
+func main() {
+	// TODO: Replace env with your own types.
+	doc := docgen.CreateDoc(env)
+
+	print(doc.Markdown())
+}
+```

docgen/docgen_test.go

@@ -1,6 +1,7 @@
 package docgen_test
 
 import (
+	"github.com/stretchr/testify/require"
 	"math"
 	"testing"
 
@@ -136,5 +137,11 @@ func TestCreateDoc_FromMap(t *testing.T) {
 		},
 	}
 
-	assert.Equal(t, litter.Sdump(expected), litter.Sdump(doc))
+	require.Equal(t, litter.Sdump(expected), litter.Sdump(doc))
+}
+
+func TestContext_Markdown(t *testing.T) {
+	doc := CreateDoc(&Env{})
+	md := doc.Markdown()
+	require.True(t, len(md) > 0)
 }

docgen/markdown.go

@@ -0,0 +1,93 @@
+package docgen
+
+import (
+	"fmt"
+	"strings"
+)
+
+func (c *Context) Markdown() string {
+	out := `### Variables
+| Name | Type |
+|------|------|
+`
+	for ident, v := range c.Variables {
+		if v.Kind == "func" {
+			continue
+		}
+		if v.Kind == "operator" {
+			continue
+		}
+		out += fmt.Sprintf("| %v | %v |\n", ident, link(v))
+	}
+
+	out += `
+### Functions
+| Name | Return type |
+|------|-------------|
+`
+	for ident, v := range c.Variables {
+		if v.Kind == "func" {
+			args := make([]string, len(v.Arguments))
+			for i, arg := range v.Arguments {
+				args[i] = link(arg)
+			}
+			out += fmt.Sprintf("| %v(%v) | %v |\n", ident, strings.Join(args, ", "), link(v.Return))
+		}
+	}
+
+	out += "\n### Types\n"
+	for name, t := range c.Types {
+		out += fmt.Sprintf("#### %v\n", name)
+		out += fields(t)
+		out += "\n"
+	}
+
+	return out
+}
+
+func link(t *Type) string {
+	if t == nil {
+		return "nil"
+	}
+	if t.Name != "" {
+		return fmt.Sprintf("[%v](#%v)", t.Name, t.Name)
+	}
+	if t.Kind == "array" {
+		return fmt.Sprintf("array(%v)", link(t.Type))
+	}
+	if t.Kind == "map" {
+		return fmt.Sprintf("map(%v => %v)", link(t.Key), link(t.Type))
+	}
+	return fmt.Sprintf("`%v`", t.Kind)
+}
+
+func fields(t *Type) string {
+	out := ""
+	foundFields := false
+	for ident, v := range t.Fields {
+		if v.Kind != "func" {
+			if !foundFields {
+				out += "| Field | Type |\n|---|---|\n"
+			}
+			foundFields = true
+
+			out += fmt.Sprintf("| %v | %v |\n", ident, link(v))
+		}
+	}
+	foundMethod := false
+	for ident, v := range t.Fields {
+		if v.Kind == "func" {
+			if !foundMethod {
+				out += "\n| Method | Returns |\n|---|---|\n"
+			}
+			foundMethod = true
+
+			args := make([]string, len(v.Arguments))
+			for i, arg := range v.Arguments {
+				args[i] = link(arg)
+			}
+			out += fmt.Sprintf("| %v(%v) | %v |\n", ident, strings.Join(args, ", "), link(v.Return))
+		}
+	}
+	return out
+}