From a5aec519db8006719b0e106c8f248cd7e337aa42 Mon Sep 17 00:00:00 2001 From: Vivek Patel Date: Fri, 7 May 2021 18:24:59 +0530 Subject: [PATCH] Tweak adoc templates - Updates path for generated docs - Adds adoc codegen for expression and fixes expr_types.gen.adoc.tpl --- pkg/codegen/afunc.go | 14 +++++ pkg/codegen/assets/afunc.gen.adoc.tpl | 63 ++++++++++++++++++++++ pkg/codegen/assets/expr_types.gen.adoc.tpl | 32 +++++++++++ pkg/codegen/assets/options.gen.adoc.tpl | 6 ++- pkg/codegen/codegen.go | 10 +++- pkg/codegen/expr_types.go | 14 +++++ pkg/options/auth.yaml | 2 +- 7 files changed, 137 insertions(+), 4 deletions(-) create mode 100644 pkg/codegen/assets/afunc.gen.adoc.tpl create mode 100644 pkg/codegen/assets/expr_types.gen.adoc.tpl diff --git a/pkg/codegen/afunc.go b/pkg/codegen/afunc.go index f9f336bc3..cf5c438b3 100644 --- a/pkg/codegen/afunc.go +++ b/pkg/codegen/afunc.go @@ -216,3 +216,17 @@ func genAutomationFunctions(tpl *template.Template, dd ...*aFuncDefs) (err error return nil } + +// genAutomationFunctionDocs look for afunc.gen.adoc.tpl and generates afunc.gen.adoc from it +func genAutomationFunctionDocs(tpl *template.Template, docsPath string, dd ...*aFuncDefs) (err error) { + var ( + typeGenAdoc = tpl.Lookup("afunc.gen.adoc.tpl") + + dst string + ) + + dst = path.Join(docsPath, "afunc.gen.adoc") + return plainTemplate(dst, typeGenAdoc, map[string]interface{}{ + "Definitions": dd, + }) +} diff --git a/pkg/codegen/assets/afunc.gen.adoc.tpl b/pkg/codegen/assets/afunc.gen.adoc.tpl new file mode 100644 index 000000000..66834e235 --- /dev/null +++ b/pkg/codegen/assets/afunc.gen.adoc.tpl @@ -0,0 +1,63 @@ +// This file is auto-generated. +// +// Changes to this file may cause incorrect behavior and will be lost if +// the code is regenerated. +// +// Definitions file that controls how this file is generated: +{{- range .Definitions }} +// - {{ .Source }} +{{- end }} + +{{ range $d := .Definitions }} += `{{ $d.Name }}` + +[cols="2m,4a,3a"] +|=== +| Name | Description | I/O + +{{- range $f := .Functions }} + +{{- if eq $f.Kind "function" }} + +| [#fnc-{{ toLower $d.Name }}-{{ toLower $f.Name }}]#<># +| {{ if $f.Meta.Description }}{{ $f.Meta.Description }}{{ end }} +| +{{- if gt (len $f.Params) 0}} +.Parameters: +{{- range $p := $f.Params}} +* {{ if $p.Required }}#*# {{ end }}`{{ if $p.Meta }} + {{- if $p.Meta.Label }} + {{- $p.Meta.Label }} + {{- else }} + {{- $p.Name }} + {{- end }} +{{- else }} + {{- $p.Name }} +{{- end }}` +({{- range $pti, $pt := $p.Types }} + `{{- $pt.WorkflowType }}`, +{{- end }}) +{{- end }} +{{- end }} + +{{- if gt (len $f.Results) 0}} + +.Results: +{{- range $r := $f.Results}} +* {{ if $r.Meta }} + {{- if $r.Meta.Label }} + {{- $r.Meta.Label }} + {{- else }} + {{- $r.Name }} + {{- end }} +{{- else }} + {{- $r.Name }} +{{- end }} (`{{ $r.WorkflowType }}`) +{{- end }} +{{- end }} + +{{- end }} +{{- end }} + +|=== +{{- end }} diff --git a/pkg/codegen/assets/expr_types.gen.adoc.tpl b/pkg/codegen/assets/expr_types.gen.adoc.tpl new file mode 100644 index 000000000..18905791a --- /dev/null +++ b/pkg/codegen/assets/expr_types.gen.adoc.tpl @@ -0,0 +1,32 @@ +// This file is auto-generated. +// +// Changes to this file may cause incorrect behavior and will be lost if +// the code is regenerated. +// +// Definitions file that controls how this file is generated: +{{- range .Definitions }} +// - {{ .Source }} +{{- end }} + +[cols="2m,3a"] +|=== +| Type | Structure +{{- range .Definitions }} +{{- range $tName, $tDef := .Types }} + {{- if gt (len $tDef.Struct) 0}} +| [#objref-{{ toLower $tName }}]#<># +| + {{- if $tDef.Struct }} +[source] +---- +{ + {{- range $s := .Struct }} + {{ $s.Name }} ({{ $s.ExprType }}) + {{- end }} +} +---- +{{ end }} + {{- end }} +{{- end }} +{{ end }} +|=== diff --git a/pkg/codegen/assets/options.gen.adoc.tpl b/pkg/codegen/assets/options.gen.adoc.tpl index dffe4ff93..9ca2f04bb 100644 --- a/pkg/codegen/assets/options.gen.adoc.tpl +++ b/pkg/codegen/assets/options.gen.adoc.tpl @@ -7,6 +7,7 @@ {{- range .Definitions }} // - {{ .Source }} {{- end }} +include::ROOT:partial$variables.adoc[] {{ range .Definitions }} = {{ .Docs.Title }} @@ -24,7 +25,10 @@ {{ if .Default -}} === Default -`{{ .Default }}` +[source] +---- +{{ .Default }} +---- {{ end -}} {{ if .Description -}} diff --git a/pkg/codegen/codegen.go b/pkg/codegen/codegen.go index 25b2af2ee..5e7b5fc96 100644 --- a/pkg/codegen/codegen.go +++ b/pkg/codegen/codegen.go @@ -14,7 +14,7 @@ import ( func Proc() { const ( - docGenBase = "/partials/generated" + docGenBase = "/generated/partials" ) var ( @@ -129,7 +129,7 @@ func Proc() { }() if len(docPath) > 0 { - docPath = strings.TrimRight(docPath, "/") + "/src/modules/ROOT" + docPath = strings.TrimRight(docPath, "/") + "/src/modules" if i, err := os.Stat(docPath); err != nil { handleError(err) } else if !i.IsDir() { @@ -212,6 +212,9 @@ func Proc() { if genCode { err = genExprTypes(tpls, exprTypeDefs...) } + if genDocs && err == nil { + err = genExprTypeDocs(tpls, docPath+docGenBase, exprTypeDefs...) + } } if outputErr(err, "failed to process expr types:\n") { @@ -282,6 +285,9 @@ func Proc() { err = genAutomationFunctions(tpls, aFuncsDefs...) } + if genDocs && err == nil { + err = genAutomationFunctionDocs(tpls, docPath+docGenBase, aFuncsDefs...) + } } if outputErr(err, "failed to process automation functions:\n") { diff --git a/pkg/codegen/expr_types.go b/pkg/codegen/expr_types.go index 893afaa16..8b96ec220 100644 --- a/pkg/codegen/expr_types.go +++ b/pkg/codegen/expr_types.go @@ -106,6 +106,20 @@ func genExprTypes(tpl *template.Template, dd ...*exprTypesDef) (err error) { return nil } +// genExprTypeDocs look for expr_types.gen.adoc.tpl and generates expr_types.gen.adoc from it +func genExprTypeDocs(tpl *template.Template, docsPath string, dd ...*exprTypesDef) (err error) { + var ( + typeGenAdoc = tpl.Lookup("expr_types.gen.adoc.tpl") + + dst string + ) + + dst = path.Join(docsPath, "expr-types.gen.adoc") + return plainTemplate(dst, typeGenAdoc, map[string]interface{}{ + "Definitions": dd, + }) +} + func (s exprTypeDef) Default() string { if s.RawDefault == "" { return "nil" diff --git a/pkg/options/auth.yaml b/pkg/options/auth.yaml index 90957e52c..b665a7c12 100644 --- a/pkg/options/auth.yaml +++ b/pkg/options/auth.yaml @@ -34,7 +34,7 @@ props: description: |- Redirect URL to be sent with OAuth2 authentication request to provider - `{provider}` placeholder is replaced with the actual value when used. + `provider` placeholder is replaced with the actual value when used. - name: externalCookieSecret default: getSecretFromEnv("external cookie secret")