Add Oneof message for generated docs (#265)

* add oneof message to gen docs * regen * ch * use sprig to trim periods * regen * regen with trim * regen again? why not * remove generated docs see #268 for details
solo-io · Sep 10, 2019 · ca24612 · ca24612
1 parent 7d0aaf3
commit ca24612
Show file tree

Hide file tree

Showing 7 changed files with 92 additions and 6 deletions.
diff --git a/Gopkg.lock b/Gopkg.lock
diff --git a/changelog/v0.10.18/add-oneof-msg.yaml b/changelog/v0.10.18/add-oneof-msg.yaml
@@ -0,0 +1,4 @@
+changelog:
+  - type: NEW_FEATURE
+    description: add oneof message to gen docs
+    issueLink: https://github.com/solo-io/solo-kit/pull/264
diff --git a/pkg/code-generator/docgen/funcs/template_funcs.go b/pkg/code-generator/docgen/funcs/template_funcs.go
@@ -3,7 +3,6 @@ package funcs
 import (
 	"bytes"
 	"fmt"
-	htmltemplate "html/template"
 	"os"
 	"path"
 	"path/filepath"
@@ -12,6 +11,10 @@ import (
 	"text/template"
 	"unicode"
 
+	htmltemplate "html/template"
+
+	"github.com/Masterminds/sprig"
+
 	"github.com/solo-io/go-utils/log"
 
 	"github.com/gogo/protobuf/protoc-gen-gogo/descriptor"
@@ -55,6 +58,7 @@ func TemplateFuncs(project *model.Project, docsOptions *options.DocsOptions) tem
 		"para":               gendoc.ParaFilter,
 		"nobr":               gendoc.NoBrFilter,
 		"fieldType":          fieldType(project),
+		"getOneofMessage":    getOneofMessage,
 		"yamlType":           yamlType,
 		"noescape":           noEscape,
 		"linkForField":       linkForField(project, docsOptions),
@@ -121,6 +125,10 @@ func TemplateFuncs(project *model.Project, docsOptions *options.DocsOptions) tem
 			return "`"
 		},
 	}
+	// add sprig funcs
+	for name, fn := range sprig.FuncMap() {
+		funcMap[name] = fn
+	}
 	funcs.Funcs = funcMap
 	return funcMap
 }
@@ -180,6 +188,41 @@ func noEscape(s string) htmltemplate.HTML {
 	return htmltemplate.HTML(s)
 }
 
+func getOneofMessage(field *protokit.FieldDescriptor) string {
+	if field.OneofIndex == nil {
+		return ""
+
+	}
+	idx := field.GetOneofIndex()
+	sameOneOf := []string{field.GetJsonName()}
+	// collect other fields which share this oneof
+	for _, f := range field.Message.Fields {
+		if f.GetName() == field.GetName() {
+			continue
+		}
+		if f.OneofIndex != nil && f.GetOneofIndex() == idx {
+			// same oneof
+			sameOneOf = append(sameOneOf, f.GetJsonName())
+		}
+	}
+	if len(sameOneOf) == 1 {
+		return ""
+	}
+
+	for i := range sameOneOf {
+		// add backtics
+		sameOneOf[i] = "`" + sameOneOf[i] + "`"
+	}
+
+	if len(sameOneOf) == 2 {
+		return fmt.Sprintf("Only one of %s or %s can be set.", sameOneOf[0], sameOneOf[1])
+	}
+
+	joinedOneofNames := strings.Join(sameOneOf[:len(sameOneOf)-2], ", ")
+	joinedOneofNames += ", or " + sameOneOf[len(sameOneOf)-1]
+	return fmt.Sprintf("Only one of %s can be set.", joinedOneofNames)
+}
+
 func fieldType(project *model.Project) func(field *protokit.FieldDescriptor) (string, error) {
 	return func(field *protokit.FieldDescriptor) (string, error) {
 		fieldTypeStr := func() string {

diff --git a/pkg/code-generator/docgen/templates/markdown/proto_file_template.go b/pkg/code-generator/docgen/templates/markdown/proto_file_template.go
@@ -64,7 +64,10 @@ func ProtoFileTemplate(project *model.Project, docsOptions *options.DocsOptions)
 | Field | Type | Description | Default |
 | ----- | ---- | ----------- |----------- | 
 {{range .Fields -}}
-| {{backtick}}{{ lower_camel (printfptr "%v" .Name) }}{{backtick}} | {{linkForField (getFileForMessage $Message) . }} | {{ remove_magic_comments (nobr .Comments.Leading) }} | {{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
+{{ $description := remove_magic_comments (nobr .Comments.Leading) }}
+{{ $oneofmsg := getOneofMessage . }}
+
+| {{backtick}}{{ lower_camel (printfptr "%v" .Name) }}{{backtick}} | {{linkForField (getFileForMessage $Message) . }} | {{ if $description }} {{trimSuffix "." $description}}.{{ end }} {{ if $oneofmsg }} {{$oneofmsg}}{{ end }} | {{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
 {{end}}
 
 ` + "`" + ` }}

diff --git a/test/mocks/api/v1/solo-kit.json b/test/mocks/api/v1/solo-kit.json
@@ -2,7 +2,6 @@
   "title": "Solo-Kit Testing",
   "name": "testing.solo.io",
   "version": "v1",
-  "docs_dir": "../doc",
   "imports": [
     "github.com/solo-io/solo-kit/api/external/kubernetes"
   ],

diff --git a/test/mocks/api/v1alpha1/solo-kit.json b/test/mocks/api/v1alpha1/solo-kit.json
@@ -2,7 +2,6 @@
   "title": "Solo-Kit Testing",
   "name": "testing.solo.io",
   "version": "v1alpha1",
-  "docs_dir": "../doc",
   "crd_group_override": "crds.testing.solo.io",
   "resource_groups": {
     "testing.solo.io": [

diff --git a/test/mocks/api/v2alpha1/solo-kit.json b/test/mocks/api/v2alpha1/solo-kit.json
@@ -2,6 +2,7 @@
   "title": "Solo-Kit Testing v2alpha1",
   "name": "testing.solo.io",
   "version": "v2alpha1",
+  "docs_dir": "docs/",
   "resource_groups": {
     "testing.solo.io": [
       {