From ca24612dd95752c1ede3b0e335eb5b35a44b5324 Mon Sep 17 00:00:00 2001 From: Scott Weiss Date: Tue, 10 Sep 2019 14:20:46 -0400 Subject: [PATCH] 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 --- Gopkg.lock | 41 ++++++++++++++++- changelog/v0.10.18/add-oneof-msg.yaml | 4 ++ .../docgen/funcs/template_funcs.go | 45 ++++++++++++++++++- .../templates/markdown/proto_file_template.go | 5 ++- test/mocks/api/v1/solo-kit.json | 1 - test/mocks/api/v1alpha1/solo-kit.json | 1 - test/mocks/api/v2alpha1/solo-kit.json | 1 + 7 files changed, 92 insertions(+), 6 deletions(-) create mode 100644 changelog/v0.10.18/add-oneof-msg.yaml diff --git a/Gopkg.lock b/Gopkg.lock index 0054c15ac..90e825adb 100644 --- a/Gopkg.lock +++ b/Gopkg.lock @@ -24,6 +24,30 @@ revision = "4b7f49dc5db2e1e6d528524d269b4181981a7ebf" version = "v11.1.1" +[[projects]] + digest = "1:3b10c6fd33854dc41de2cf78b7bae105da94c2789b6fa5b9ac9e593ea43484ac" + name = "github.com/Masterminds/goutils" + packages = ["."] + pruneopts = "UT" + revision = "41ac8693c5c10a92ea1ff5ac3a7f95646f6123b0" + version = "v1.1.0" + +[[projects]] + digest = "1:55388fd080150b9a072912f97b1f5891eb0b50df43401f8b75fb4273d3fec9fc" + name = "github.com/Masterminds/semver" + packages = ["."] + pruneopts = "UT" + revision = "c7af12943936e8c39859482e61f0574c2fd7fc75" + version = "v1.4.2" + +[[projects]] + digest = "1:ab506cfc00b11d6d406789c15abb0b341e8db076640e3f5255615a7e327398c1" + name = "github.com/Masterminds/sprig" + packages = ["."] + pruneopts = "UT" + revision = "258b00ffa7318e8b109a141349980ffbd30a35db" + version = "v2.20.0" + [[projects]] digest = "1:1c9dffe45896d21dc8e183fdc3cdb405249e6c7dd3d00792e534af3597d5e4fc" name = "github.com/avast/retry-go" @@ -363,6 +387,14 @@ pruneopts = "UT" revision = "a1dbeea552b7c8df4b542c66073e393de198a800" +[[projects]] + digest = "1:f9a5e090336881be43cfc1cf468330c1bdd60abdc9dd194e0b1ab69f4b94dd7c" + name = "github.com/huandu/xstrings" + packages = ["."] + pruneopts = "UT" + revision = "f02667b379e2fb5916c3cda2cf31e0eb885d79f8" + version = "v1.2.0" + [[projects]] branch = "master" digest = "1:32a62f9393d4b982aae329c535e81e77146924f96ef8b069e4d16c92e22db147" @@ -655,9 +687,13 @@ [[projects]] branch = "master" - digest = "1:3f3a05ae0b95893d90b9b3b5afdb79a9b3d96e4e36e099d841ae602e4aca0da8" + digest = "1:69b3fcb7a41b18436a85471cbdcfc70ad10ba3206f8c87563e1c773610e1bcad" name = "golang.org/x/crypto" - packages = ["ssh/terminal"] + packages = [ + "pbkdf2", + "scrypt", + "ssh/terminal", + ] pruneopts = "UT" revision = "a2144134853fc9a27a7b1e3eb4f19f1a76df13c9" @@ -1240,6 +1276,7 @@ analyzer-name = "dep" analyzer-version = 1 input-imports = [ + "github.com/Masterminds/sprig", "github.com/envoyproxy/go-control-plane/envoy/api/v2", "github.com/envoyproxy/go-control-plane/envoy/api/v2/core", "github.com/envoyproxy/go-control-plane/envoy/service/discovery/v2", diff --git a/changelog/v0.10.18/add-oneof-msg.yaml b/changelog/v0.10.18/add-oneof-msg.yaml new file mode 100644 index 000000000..a378540ea --- /dev/null +++ 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 index 7c5ce5e02..3059840ac 100644 --- 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 index 8db65db44..36f3c19ce 100644 --- 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 index 801367bc9..7da2c22d1 100644 --- 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 index c90ef0c26..997179db0 100644 --- 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 index fd99b3e8a..236eda0c9 100644 --- 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": [ {