Merge pull request #1151 from nyaruka/version_docs

Add migration versions to auto-generated docs

cmd/docgen/docs/docstrs.go

@@ -8,6 +8,8 @@ import (
 	"regexp"
 	"sort"
 	"strings"
+
+	"github.com/Masterminds/semver"
 )
 
 var searchDirs = []string{
@@ -18,6 +20,7 @@ var searchDirs = []string{
 	"flows",
 	"flows/actions",
 	"flows/definition",
+	"flows/definition/migrations",
 	"flows/events",
 	"flows/inputs",
 	"flows/resumes",
@@ -61,9 +64,17 @@ func FindAllTaggedItems(baseDir string) (map[string][]*TaggedItem, error) {
 		}
 	}
 
-	for _, v := range items {
-		// sort items by their tag value
-		sort.SliceStable(v, func(i, j int) bool { return v[i].tagValue < v[j].tagValue })
+	for t, v := range items {
+		if t == "version" {
+			sort.SliceStable(v, func(i, j int) bool {
+				iv := semver.MustParse(v[i].tagTitle)
+				jv := semver.MustParse(v[j].tagTitle)
+				return jv.LessThan(iv)
+			})
+		} else {
+			// sort items by their tag value
+			sort.SliceStable(v, func(i, j int) bool { return v[i].tagValue < v[j].tagValue })
+		}
 	}
 
 	return items, nil
@@ -91,6 +102,9 @@ func findTaggedItems(baseDir string, searchDir string, callback func(item *Tagge
 			for _, m := range t.Methods {
 				tryToParse(m.Doc, m.Name)
 			}
+			for _, m := range t.Funcs {
+				tryToParse(m.Doc, m.Name)
+			}
 		}
 		for _, t := range p.Funcs {
 			tryToParse(t.Doc, t.Name)

cmd/docgen/docs/html.go

@@ -35,14 +35,15 @@ var Templates = []struct {
 	Title         string
 	Path          string
 	ContainsTypes []string // used for resolving links
+	TOC           bool
 }{
-	{"Flow Specification", "index.md", nil},
-	{"Flows", "flows.md", []string{"action", "router", "wait"}},
-	{"Expressions", "expressions.md", []string{"type", "operator", "function"}},
-	{"Context", "context.md", []string{"context"}},
-	{"Routing", "routing.md", []string{"test"}},
-	{"Sessions", "sessions.md", []string{"event", "trigger", "resume"}},
-	{"Assets", "assets.md", []string{"asset"}},
+	{"Flow Specification", "index.md", []string{"version"}, false},
+	{"Flows", "flows.md", []string{"action", "router", "wait"}, true},
+	{"Expressions", "expressions.md", []string{"type", "operator", "function"}, true},
+	{"Context", "context.md", []string{"context"}, true},
+	{"Routing", "routing.md", []string{"test"}, true},
+	{"Sessions", "sessions.md", []string{"event", "trigger", "resume"}, true},
+	{"Assets", "assets.md", []string{"asset"}, true},
 }
 
 // ContextFunc is a function which produces values to put the template context
@@ -107,7 +108,7 @@ func renderTemplateDocs(baseDir string, outputDir string, items map[string][]*Ta
 		htmlTemplate := path.Join(baseDir, "cmd/docgen/templates/template.html")
 		htmlContext := map[string]string{"title": template.Title}
 
-		if err := renderHTML(renderedPath, htmlPath, htmlTemplate, htmlContext); err != nil {
+		if err := renderHTML(renderedPath, htmlPath, htmlTemplate, template.TOC, htmlContext); err != nil {
 			return errors.Wrapf(err, "error rendering HTML from %s to %s", renderedPath, htmlPath)
 		}
 
@@ -136,15 +137,17 @@ func renderTemplate(src, dst string, context map[string]string, resolver urlReso
 }
 
 // converts a markdown file to HTML
-func renderHTML(src, dst, htmlTemplate string, variables map[string]string) error {
+func renderHTML(src, dst, htmlTemplate string, toc bool, variables map[string]string) error {
 	panDocArgs := []string{
 		"--from=markdown",
 		"--to=html",
 		"-o", dst,
 		"--standalone",
 		"--template=" + htmlTemplate,
-		"--toc",
-		"--toc-depth=1",
+	}
+
+	if toc {
+		panDocArgs = append(panDocArgs, "--toc", "--toc-depth=1")
 	}
 
 	for k, v := range variables {

cmd/docgen/docs/html_renderers.go

@@ -37,6 +37,7 @@ func init() {
 	registerContextFunc(createItemListContextFunc("event", renderEventDoc))
 	registerContextFunc(createItemListContextFunc("trigger", renderTriggerDoc))
 	registerContextFunc(createItemListContextFunc("resume", renderResumeDoc))
+	registerContextFunc(createItemListContextFunc("version", renderVersionDoc))
 	registerContextFunc(renderRootContext)
 }
 
@@ -375,6 +376,14 @@ func renderResumeDoc(output *strings.Builder, item *TaggedItem, session flows.Se
 	return nil
 }
 
+func renderVersionDoc(output *strings.Builder, item *TaggedItem, session flows.Session, voiceSession flows.Session) error {
+	output.WriteString(renderItemTitle(item))
+	output.WriteString(strings.Join(item.description, "\n"))
+	output.WriteString("\n")
+
+	return nil
+}
+
 func renderItemTitle(item *TaggedItem) string {
 	return fmt.Sprintf("<h2 class=\"item_title\"><a name=\"%[1]s:%[2]s\" href=\"#%[1]s:%[2]s\">%[3]s</a></h2>\n\n", item.tagName, item.tagValue, item.tagTitle)
 }

cmd/docgen/templates/index.md

@@ -5,3 +5,9 @@
  * [Routing](routing.html)
  * [Sessions](sessions.html)
  * [Assets](assets.html)
+
+# Versions
+
+<div class="versions">
+{{ .versionDocs }}
+</div>

flows/definition/migrations/13_x.go

@@ -1,17 +1,19 @@
 package migrations
 
 import (
-	"github.com/nyaruka/gocommon/uuids"
-
 	"github.com/Masterminds/semver"
+	"github.com/nyaruka/gocommon/uuids"
 )
 
 func init() {
 	registerMigration(semver.MustParse("13.2.0"), Migrate13_2)
 	registerMigration(semver.MustParse("13.1.0"), Migrate13_1)
 }
 
-// Migrate13_2 replaces "base" as a flow language with "und" (Undetermined)
+// Migrate13_2 replaces `base` as a flow language with `und` which indicates text with undetermined language
+// in ISO-639-3.
+//
+// @version 13_2 "13.2"
 func Migrate13_2(f Flow, cfg *Config) (Flow, error) {
 	language, _ := f["language"].(string)
 	localization := f.Localization()
@@ -27,7 +29,9 @@ func Migrate13_2(f Flow, cfg *Config) (Flow, error) {
 	return f, nil
 }
 
-// Migrate13_1 adds UUID to send_msg templating
+// Migrate13_1 adds a `UUID` property to templating objects [action:send_msg] actions.
+//
+// @version 13_1 "13.1"
 func Migrate13_1(f Flow, cfg *Config) (Flow, error) {
 	for _, node := range f.Nodes() {
 		for _, action := range node.Actions() {