Docs: Generate client pages (#45)

cmd/docgen/main.go

@@ -76,13 +76,6 @@ func main() {
 				os.Exit(1)
 			}
 
-			contentFile := filepath.Join(workDir, postContentPath, serviceName+".md")
-			err = ioutil.WriteFile(contentFile, append([]byte("---\ntitle: "+serviceName+"\n---\n"), dat...), 0777)
-			if err != nil {
-				fmt.Printf("Failed to write post content to %v:\n%v\n", contentFile, string(outp))
-				os.Exit(1)
-			}
-
 			apiJSON := filepath.Join(serviceDir, "api-"+serviceName+".json")
 			js, err := ioutil.ReadFile(apiJSON)
 			if err != nil {
@@ -99,7 +92,7 @@ func main() {
 				fmt.Println("Failed to unmarshal", err)
 				os.Exit(1)
 			}
-			err = saveSpec(contentFile, spec)
+			err = saveSpec(dat, contentDir, serviceName, spec)
 			if err != nil {
 				fmt.Println("Failed to save to spec file", err)
 				os.Exit(1)
@@ -129,68 +122,139 @@ func main() {
 	}
 }
 
-func saveSpec(filepath string, spec *openapi3.Swagger) error {
-	fi, err := os.OpenFile(filepath, os.O_APPEND|os.O_WRONLY, os.ModeAppend)
-	if err != nil {
-		return err
-	}
-	//spec.Paths[0].Parameters[0].MarshalJSON()
-	//spec.Paths[0].Options
-	//spec.Paths[0].Post.RequestBody.
-	tmpl, err := template.New("test").Funcs(template.FuncMap{
-		"params": func(p openapi3.Parameters) string {
-			ls := ""
-			for _, v := range p {
-				//if v.Value.In == "body" {
-				bs, _ := v.MarshalJSON()
-				ls += string(bs) + ", "
-				//}
-			}
-			return ls
-		},
-		// @todo should take SpecRef here not RequestBodyRef
-		"schemaJSON": func(ref string) string {
-			for k, v := range spec.Components.Schemas {
-				// ie. #/components/requestBodies/PostsSaveRequest contains
-				// SaveRequest, can't see any other way to correlate
-				if strings.HasSuffix(ref, k) {
-					bs, _ := json.MarshalIndent(schemaToMap(v, spec.Components.Schemas), "", "  ")
-					return string(bs)
+type specType struct {
+	name          string
+	tag           string
+	includeReadme bool
+	filePostFix   string
+	titlePostFix  string
+	template      string
+}
+
+var specTypes = []specType{
+	{
+		name:          "default markdown",
+		tag:           "Readme",
+		filePostFix:   ".md",
+		template:      defTempl,
+		includeReadme: true,
+	},
+	{
+		name:          "microjs markdown",
+		tag:           "Micro.js",
+		filePostFix:   "-microjs.md",
+		titlePostFix:  " Micro.js",
+		template:      microJSTempl,
+		includeReadme: false,
+	},
+}
+
+var servicesToTags = map[string][]string{
+	"users":      []string{"Backend"},
+	"helloworld": []string{"Backend"},
+	"emails":     []string{"Communications"},
+	"sms":        []string{"Communications"},
+	"posts":      []string{"Headless CMS"},
+	"tags":       []string{"Headless CMS"},
+	"feeds":      []string{"Headless CMS"},
+	"chat":       []string{"Communications"},
+	"geocoding":  []string{"Logistics"},
+	"places":     []string{"Logistics"},
+	"routing":    []string{"Logistics"},
+	"etas":       []string{"Logistics"},
+	"notes":      []string{"Misc"},
+	"messages":   []string{"Misc"},
+}
+
+func saveSpec(originalMarkDown []byte, contentDir, serviceName string, spec *openapi3.Swagger) error {
+	for _, v := range specTypes {
+		fmt.Println("Processing ", v.name)
+		contentFile := filepath.Join(contentDir, serviceName+v.filePostFix)
+		var app []byte
+		if v.includeReadme {
+			app = originalMarkDown
+		}
+		tags := []string{v.tag}
+		serviceTags, ok := servicesToTags[serviceName]
+		if ok {
+			tags = append(tags, serviceTags...)
+		}
+		tagsString := "\n- " + strings.Join(tags, "\n- ")
+
+		err := ioutil.WriteFile(contentFile, append([]byte("---\ntitle: "+serviceName+v.titlePostFix+"\nservicename: "+serviceName+"\nlabels: "+tagsString+"\n---\n"), app...), 0777)
+		if err != nil {
+			fmt.Printf("Failed to write post content to %v:\n%v\n", err)
+			os.Exit(1)
+		}
+		fi, err := os.OpenFile(contentFile, os.O_APPEND|os.O_WRONLY, os.ModeAppend)
+		if err != nil {
+			return err
+		}
+		tmpl, err := template.New("test").Funcs(template.FuncMap{
+			"params": func(p openapi3.Parameters) string {
+				ls := ""
+				for _, v := range p {
+					//if v.Value.In == "body" {
+					bs, _ := v.MarshalJSON()
+					ls += string(bs) + ", "
+					//}
 				}
-			}
-
-			return "Schema related to " + ref + " not found"
-
-		},
-		"schemaDescription": func(ref string) string {
-			for k, v := range spec.Components.Schemas {
-				// ie. #/components/requestBodies/PostsSaveRequest contains
-				// SaveRequest, can't see any other way to correlate
-				if strings.HasSuffix(ref, k) {
-					return v.Value.Description
+				return ls
+			},
+			// @todo should take SpecRef here not RequestBodyRef
+			"schemaJSON": func(prepend int, ref string) string {
+				for k, v := range spec.Components.Schemas {
+					// ie. #/components/requestBodies/PostsSaveRequest contains
+					// SaveRequest, can't see any other way to correlate
+					if strings.HasSuffix(ref, k) {
+						bs, _ := json.MarshalIndent(schemaToMap(v, spec.Components.Schemas), "", strings.Repeat(" ", prepend)+"  ")
+						// last line wont get prepended so we fix that here
+						parts := strings.Split(string(bs), "\n")
+						// skip if it's only 1 line, ie it's '{}'
+						if len(parts) <= 1 {
+							return string(bs)
+						}
+						parts[len(parts)-1] = strings.Repeat(" ", prepend) + parts[len(parts)-1]
+						return strings.Join(parts, "\n")
+					}
 				}
-			}
 
-			return "Schema related to " + ref + " not found"
+				return "Schema related to " + ref + " not found"
 
-		},
-		// turn chat/Chat/History
-		// to Chat History
-		"titleize": func(s string) string {
-			parts := strings.Split(s, "/")
-			if len(parts) > 2 {
-				return strings.Join(parts[2:], " ")
-			}
-			return strings.Join(parts, " ")
-		},
-		"firstResponseRef": func(rs openapi3.Responses) string {
-			return rs.Get(200).Ref
-		},
-	}).Parse(templ)
-	if err != nil {
-		panic(err)
+			},
+			"schemaDescription": func(ref string) string {
+				for k, v := range spec.Components.Schemas {
+					// ie. #/components/requestBodies/PostsSaveRequest contains
+					// SaveRequest, can't see any other way to correlate
+					if strings.HasSuffix(ref, k) {
+						return v.Value.Description
+					}
+				}
+
+				return "Schema related to " + ref + " not found"
+			},
+			// turn chat/Chat/History
+			// to Chat History
+			"titleize": func(s string) string {
+				parts := strings.Split(s, "/")
+				if len(parts) > 2 {
+					return strings.Join(parts[2:], " ")
+				}
+				return strings.Join(parts, " ")
+			},
+			"firstResponseRef": func(rs openapi3.Responses) string {
+				return rs.Get(200).Ref
+			},
+		}).Parse(v.template)
+		if err != nil {
+			panic(err)
+		}
+		err = tmpl.Execute(fi, spec)
+		if err != nil {
+			return err
+		}
 	}
-	return tmpl.Execute(fi, spec)
+	return nil
 }
 
 func schemaToMap(spec *openapi3.SchemaRef, schemas map[string]*openapi3.SchemaRef) map[string]interface{} {
@@ -226,7 +290,7 @@ func schemaToMap(spec *openapi3.SchemaRef, schemas map[string]*openapi3.SchemaRe
 	return recurse(spec.Value.Properties)
 }
 
-const templ = `
+const defTempl = `
 ## cURL
 
 {{ range $key, $value := .Paths }}
@@ -238,9 +302,39 @@ being lifted correctly from the proto by the openapi spec generator -->
 > curl 'https://api.m3o.com{{ $key }}' \
   -H 'micro-namespace: $yourNamespace' \
   -H 'authorization: Bearer $yourToken' \
-  -d {{ $value.Post.RequestBody.Ref | schemaJSON }};
+  -d {{ $value.Post.RequestBody.Ref | schemaJSON 0 }};
 # Response
-{{ $value.Post.Responses | firstResponseRef | schemaJSON }}
+{{ $value.Post.Responses | firstResponseRef | schemaJSON 0 }}
+` + "```" + `
+
+{{ end }}
+`
+
+const microJSTempl = `
+## Micro.js
+
+{{ range $key, $value := .Paths }}
+### {{ $key | titleize }}
+<!-- We use the request body description here as endpoint descriptions are not
+being lifted correctly from the proto by the openapi spec generator -->
+{{ $value.Post.RequestBody.Ref | schemaDescription }}
+` + "```" + `html
+<script src="https://web.m3o.com/assets/micro.js"></script>
+<script type="text/javascript">
+  document.addEventListener("DOMContentLoaded", function (event) {
+    // Login is only required for endpoints doing authorization
+    Micro.requireLogin(function () {
+      Micro.post(
+        "{{ $key }}",
+        "micro",
+        {{ $value.Post.RequestBody.Ref | schemaJSON 8 }},
+        function (data) {
+          console.log("Success.");
+        }
+      );
+    });
+  });
+</script>
 ` + "```" + `
 
 {{ end }}

docs/hugo-tania/layouts/_default/index.html

@@ -27,11 +27,11 @@
 
 {{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }}
 {{ $projects := where .Site.RegularPages "Section" "projects" }}
-{{ $pages = first (default 100 .Site.Params.homePosts) (sort (where .Site.RegularPages "Type" "in" .Site.Params.mainSections) "Date" "desc") }}
 
 <div class="container">
   <section>
     <div class="posts">
+      {{ $pages = .Site.Taxonomies.labels.readme }}
       {{ range $i,$e := $pages }}
 
       {{if modBool $i 2}}
@@ -58,6 +58,8 @@
       {{ end }}
 
       {{ end }}
+
+      <!-- todo: do not copypaste it all -->
     </div>
   </section>
   {{ if gt (len $projects) 0}}

docs/hugo-tania/layouts/_default/single.html

@@ -5,18 +5,23 @@
         <header class="article-header">
             <div class="thumb">
                 <div>
-                    <h1>{{ .Title }}</h1>
+                    <h1><a href="/{{ .Params.servicename }}">{{ .Params.servicename }}</a></h1>
                     <div>
-                        <a href="/{{ .Title }}/api"><u>API Spec</u></a>
+                        <a href="/{{ .Params.servicename }}"><u>Readme</u></a>
                         &nbsp;
-                        <a href="{{ $.Site.Params.source }}/tree/master/{{ .Title }}"><u>Source</u></a>
+                        <a href="/{{ .Params.servicename }}-microjs"><u>Micro.js</u></a>
+                        &nbsp;
+                        <a href="/{{ .Params.servicename }}/api"><u>API Spec</u></a>
+                        &nbsp;
+                        <a href="{{ $.Site.Params.source }}/tree/master/{{ .Params.servicename }}"><u>Source</u></a>
                     </div>
                     <div class="post-meta">
                         <!-- <div>
                             By {{ .Params.author }} on <time>{{ .Date.Format "January 02, 2006" }}</time>
-                        </div> -->
+                        </div>
+                        -->
                         <div class="tags">
-                            {{ range (.GetTerms "tags") }}
+                            {{ range (.GetTerms "labels") }}
                             <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
                             {{ end }}
                         </div>

docs/hugo-tania/site/config.yaml

@@ -30,3 +30,6 @@ markup:
 
 permalinks:
   post: /:filename
+
+taxonomies:
+  tag: "labels"

groups/Makefile

@@ -7,8 +7,13 @@ init:
 	go get github.com/micro/micro/v3/cmd/protoc-gen-micro
 .PHONY: proto
 proto:
-	protoc --proto_path=. --micro_out=. --go_out=:. proto/groups.proto
-	
+	protoc --openapi_out=. --proto_path=. --micro_out=. --go_out=:. proto/groups.proto
+
+.PHONY: docs
+docs:
+	protoc --openapi_out=. --proto_path=. --micro_out=. --go_out=:. proto/groups.proto
+	@redoc-cli bundle api-groups.json
+
 .PHONY: build
 build:
 	go build -o groups *.go

groups/proto/groups.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go. DO NOT EDIT.
 // versions:
-// 	protoc-gen-go v1.23.0
-// 	protoc        v3.13.0
+// 	protoc-gen-go v1.25.0
+// 	protoc        v3.6.1
 // source: proto/groups.proto
 
 package groups