feat(website): add godoc-style documentation to gno packages

gnoland/website/main.go

@@ -23,13 +23,15 @@ import (
 	"github.com/gorilla/mux"
 	"github.com/gotuna/gotuna"
 
+	"github.com/gnolang/gno/gnoland/website/pkgs/doc"
 	"github.com/gnolang/gno/gnoland/website/static" // for static files
 	"github.com/gnolang/gno/pkgs/sdk/vm"            // for error types
 	// "github.com/gnolang/gno/pkgs/sdk"               // for baseapp (info, status)
 )
 
 const (
-	qFileStr = "vm/qfile"
+	qFileStr  = "vm/qfile"
+	qFilesStr = "vm/qfiles"
 )
 
 var flags struct {
@@ -319,50 +321,59 @@ func handlerPackageFile(app gotuna.App) http.Handler {
 		vars := mux.Vars(r)
 		pkgpath := "gno.land/p/" + vars["filepath"]
 		diruri, filename := std.SplitFilepath(pkgpath)
-		if filename == "" && diruri == pkgpath {
-			// redirect to diruri + "/"
-			http.Redirect(w, r, "/p/"+vars["filepath"]+"/", http.StatusFound)
+		if filename != "" {
+			renderPackageFile(app, w, r, diruri, filename)
 			return
 		}
-		renderPackageFile(app, w, r, diruri, filename)
+		renderPackage(app, w, r, diruri)
 	})
 }
 
+func renderPackage(app gotuna.App, w http.ResponseWriter, r *http.Request, diruri string) {
+	qpath := qFilesStr
+	data := []byte(diruri)
+	res, err := makeRequest(qpath, data)
+	if err != nil {
+		writeError(w, err)
+		return
+	}
+
+	var files map[string]string
+	if err := json.Unmarshal(res.Data, &files); err != nil {
+		writeError(w, err)
+		return
+	}
+
+	pkgdoc, err := doc.New(diruri, files)
+	if err != nil {
+		writeError(w, err)
+		return
+	}
+
+	tmpl := app.NewTemplatingEngine()
+	tmpl.Set("DirURI", diruri)
+	tmpl.Set("DirPath", pathOf(diruri))
+	tmpl.Set("Package", pkgdoc)
+	tmpl.Render(w, r, "package_dir.html", "funcs.html")
+}
+
 func renderPackageFile(app gotuna.App, w http.ResponseWriter, r *http.Request, diruri string, filename string) {
-	if filename == "" {
-		// Request is for a folder.
-		qpath := qFileStr
-		data := []byte(diruri)
-		res, err := makeRequest(qpath, data)
-		if err != nil {
-			writeError(w, err)
-			return
-		}
-		files := strings.Split(string(res.Data), "\n")
-		// Render template.
-		tmpl := app.NewTemplatingEngine()
-		tmpl.Set("DirURI", diruri)
-		tmpl.Set("DirPath", pathOf(diruri))
-		tmpl.Set("Files", files)
-		tmpl.Render(w, r, "package_dir.html", "funcs.html")
-	} else {
-		// Request is for a file.
-		filepath := diruri + "/" + filename
-		qpath := qFileStr
-		data := []byte(filepath)
-		res, err := makeRequest(qpath, data)
-		if err != nil {
-			writeError(w, err)
-			return
-		}
-		// Render template.
-		tmpl := app.NewTemplatingEngine()
-		tmpl.Set("DirURI", diruri)
-		tmpl.Set("DirPath", pathOf(diruri))
-		tmpl.Set("FileName", filename)
-		tmpl.Set("FileContents", string(res.Data))
-		tmpl.Render(w, r, "package_file.html", "funcs.html")
+	// Request is for a file.
+	filepath := diruri + "/" + filename
+	qpath := qFileStr
+	data := []byte(filepath)
+	res, err := makeRequest(qpath, data)
+	if err != nil {
+		writeError(w, err)
+		return
 	}
+	// Render template.
+	tmpl := app.NewTemplatingEngine()
+	tmpl.Set("DirURI", diruri)
+	tmpl.Set("DirPath", pathOf(diruri))
+	tmpl.Set("FileName", filename)
+	tmpl.Set("FileContents", string(res.Data))
+	tmpl.Render(w, r, "package_file.html", "funcs.html")
 }
 
 func makeRequest(qpath string, data []byte) (res *abci.ResponseQuery, err error) {

gnoland/website/pkgs/doc/doc.go

@@ -0,0 +1,82 @@
+package doc
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"sort"
+	"strings"
+)
+
+func New(pkgPath string, files map[string]string) (*Package, error) {
+	p := Package{
+		ImportPath: pkgPath,
+		Filenames:  make([]string, 0, len(files)),
+	}
+
+	fset := token.NewFileSet()
+	gnoFiles := make(map[string]*ast.File)
+
+	for filename, fileContent := range files {
+		p.Filenames = append(p.Filenames, filename)
+
+		f, err := parser.ParseFile(fset, filename, fileContent, parser.ParseComments)
+		if err != nil {
+			return nil, err
+		}
+
+		ast.FileExports(f)
+
+		if strings.HasSuffix(filename, "_test.gno") {
+			continue
+		}
+
+		gnoFiles[filename] = f
+
+		if f.Doc != nil {
+			doc := f.Doc.Text()
+			if p.Doc != "" {
+				p.Doc += "\n"
+			}
+			p.Doc += doc
+		}
+	}
+
+	sort.Strings(p.Filenames)
+
+	astPkg, _ := ast.NewPackage(fset, gnoFiles, nil, nil)
+
+	p.Name = astPkg.Name
+
+	ast.Inspect(astPkg, func(n ast.Node) bool {
+		switch x := n.(type) {
+		case *ast.FuncDecl:
+			fn := extractFunc(x)
+			p.Funcs = append(p.Funcs, fn)
+
+		case *ast.GenDecl:
+			if x.Tok == token.VAR {
+				value, _ := extractValue(fset, x)
+				p.Vars = append(p.Vars, value)
+			}
+			if x.Tok == token.CONST {
+				value, _ := extractValue(fset, x)
+				p.Consts = append(p.Consts, value)
+			}
+			if x.Tok == token.TYPE {
+				for _, spec := range x.Specs {
+					if ts, ok := spec.(*ast.TypeSpec); ok {
+						newType, _ := extractType(fset, ts)
+						p.Types = append(p.Types, newType)
+					}
+				}
+			}
+		}
+
+		return true
+	})
+
+	p.populateType()
+
+	return &p, nil
+}

gnoland/website/pkgs/doc/types.go

@@ -0,0 +1,165 @@
+package doc
+
+import (
+	"strings"
+)
+
+type Package struct {
+	ImportPath string
+	Name       string
+	Doc        string
+	Filenames  []string
+	Funcs      []*Func
+	Methods    []*Func
+	Vars       []*Value
+	Consts     []*Value
+	Types      []*Type
+	Examples   []*Example
+}
+
+func (p *Package) populateType() {
+	p.populateTypeWithMethods()
+	p.populateTypeWithFuncs()
+	p.populateTypeWithValue()
+}
+
+func (p *Package) populateTypeWithMethods() {
+	for _, t := range p.Types {
+		matchedFuncs := make([]*Func, 0)
+		remainingFuncs := make([]*Func, 0)
+		for _, fn := range p.Funcs {
+			if fn.Recv == nil {
+				remainingFuncs = append(remainingFuncs, fn)
+				continue
+			}
+			for _, n := range fn.Recv {
+				if n == t.Name || "*"+n == t.Name {
+					matchedFuncs = append(matchedFuncs, fn)
+				} else {
+					remainingFuncs = append(remainingFuncs, fn)
+				}
+			}
+		}
+		t.Methods = matchedFuncs
+		p.Funcs = remainingFuncs
+	}
+}
+
+func (p *Package) populateTypeWithFuncs() {
+	for _, t := range p.Types {
+		var matchedFuncs []*Func
+		var remainingFuncs []*Func
+
+		for _, fn := range p.Funcs {
+			foundMatch := false
+
+			for _, r := range fn.Returns {
+				if r.Type == t.Name || strings.HasPrefix(r.Type, "*") && r.Type[1:] == t.Name {
+					matchedFuncs = append(matchedFuncs, fn)
+					foundMatch = true
+					break
+				}
+			}
+
+			if !foundMatch {
+				remainingFuncs = append(remainingFuncs, fn)
+			}
+		}
+
+		t.Funcs = matchedFuncs
+		p.Funcs = remainingFuncs
+	}
+}
+
+func (p *Package) populateTypeWithValue() {
+	for _, t := range p.Types {
+		var matchedVars []*Value
+		var matchedConsts []*Value
+
+		var remainingVars []*Value
+		for _, v := range p.Vars {
+			var matched bool
+			for _, item := range v.Items {
+				if item.Type == t.Name {
+					matchedVars = append(matchedVars, v)
+					matched = true
+					break
+				}
+			}
+			if !matched {
+				remainingVars = append(remainingVars, v)
+			}
+		}
+		p.Vars = remainingVars
+
+		var remainingConsts []*Value
+		for _, c := range p.Consts {
+			var matched bool
+			for _, item := range c.Items {
+				if item.Type == t.Name {
+					matchedConsts = append(matchedConsts, c)
+					matched = true
+					break
+				}
+			}
+			if !matched {
+				remainingConsts = append(remainingConsts, c)
+			}
+		}
+		p.Consts = remainingConsts
+
+		t.Vars = matchedVars
+		t.Consts = matchedConsts
+	}
+}
+
+type Example struct {
+	Name   string
+	Doc    string
+	Code   string
+	Output []string
+	Play   bool
+}
+
+type Value struct {
+	Doc       string
+	Names     []string
+	Items     []*ValueItem
+	Signature string
+}
+
+type ValueItem struct {
+	Doc   string
+	Type  string
+	Name  string
+	Value string
+}
+
+type FuncParam struct {
+	Type  string
+	Names []string
+}
+
+type FuncReturn struct {
+	Type  string
+	Names []string
+}
+
+type Func struct {
+	Doc       string
+	Name      string
+	Params    []*FuncParam
+	Returns   []*FuncReturn
+	Recv      []string
+	Signature string
+}
+
+type Type struct {
+	Doc        string
+	Name       string
+	Definition string
+	Consts     []*Value
+	Vars       []*Value
+	Funcs      []*Func
+	Methods    []*Func
+}