From 402289016dc2c52f3e2eed981cbbd9fa0fe911ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Toma=C5=BE=20Jerman?= Date: Sat, 5 Dec 2020 10:30:10 +0100 Subject: [PATCH] Doc codegen tweaks & cleanup --- pkg/codegen/assets/events.gen.adoc.tpl | 21 +++++++++++------ pkg/codegen/assets/options.gen.adoc.tpl | 30 +++++++++++-------------- pkg/codegen/codegen.go | 8 +++---- pkg/codegen/events.go | 2 +- pkg/codegen/options.go | 2 +- pkg/options/HTTPClient.yaml | 7 ++++-- pkg/options/SMTP.yaml | 4 ++-- pkg/options/auth.yaml | 4 ++-- pkg/options/sentry.yaml | 2 +- pkg/options/upgrade.yaml | 9 ++++---- pkg/options/waitFor.yaml | 16 +++++++------ 11 files changed, 56 insertions(+), 49 deletions(-) diff --git a/pkg/codegen/assets/events.gen.adoc.tpl b/pkg/codegen/assets/events.gen.adoc.tpl index 885cb899f..f9f78b2c7 100644 --- a/pkg/codegen/assets/events.gen.adoc.tpl +++ b/pkg/codegen/assets/events.gen.adoc.tpl @@ -8,37 +8,44 @@ // - {{ .Source }} {{- end }} += Resources and events {{- range .Definitions }} {{- range .Resources }} -= {{ .ResourceString }} +== {{ .ResourceString }} -== Events +=== Events -.Events: +{{- if .BeforeAfter }} +.Before/after events: {{- range $ba := .BeforeAfter }} * `before('{{ $ba }}')` {{- end }} {{- range $ba := .BeforeAfter }} * `after('{{ $ba }}')` {{- end }} +{{- end }} + +{{ if .On -}} +.On events: {{- range $on := .On }} * `on('{{ $on }}')` {{- end }} +{{- end }} -== Argument properties +=== Exec arguments .Argument properties: [%header, cols=3*] |=== -|Name|Type|Immutable +|Name|Type|Mutable {{- range $p := .Properties }} | `{{ $p.Name }}` | `{{ $p.Type }}` {{- if $p.Immutable }} -| yes -{{ else }} | no +{{ else }} +| yes {{ end -}} {{ end -}} diff --git a/pkg/codegen/assets/options.gen.adoc.tpl b/pkg/codegen/assets/options.gen.adoc.tpl index ed74c6ddb..580f753a1 100644 --- a/pkg/codegen/assets/options.gen.adoc.tpl +++ b/pkg/codegen/assets/options.gen.adoc.tpl @@ -8,26 +8,22 @@ // - {{ .Source }} {{- end }} - += ENV options {{ range .Definitions }} - -= {{ .Docs.Title }} - +== {{ .Docs.Title }} +{{ if .Docs.Intro }} {{ .Docs.Intro }} +{{ end }} +{{- range .Properties }} +=== *{{ toUpper .Env }}* `{{ .Type }}` -{{ range .Properties }} - -== *{{ toUpper .Env }}* `{{ .Type }}` - -{{ if .Default }} +{{ if or .Default .Description -}} +{{ if .Default -}} Default:: - `{{ .Default }}` + `{{ .Default }}` {{ end -}} -{{ if .Description }} +{{ if .Description -}} Description:: - {{ .Description }} -{{ end -}} - -{{ end }} -{{ end }} - + {{ .Description }} +{{ end -}}{{ end -}} +{{ end }}{{ end }} \ No newline at end of file diff --git a/pkg/codegen/codegen.go b/pkg/codegen/codegen.go index 1a05f38be..c17dbda5e 100644 --- a/pkg/codegen/codegen.go +++ b/pkg/codegen/codegen.go @@ -14,7 +14,7 @@ import ( func Proc() { const ( - docPathOptions = "/dev-ops-guide/server-configuration" + docGenBase = "/partials/generated" ) var ( @@ -117,7 +117,7 @@ func Proc() { }() if len(docPath) > 0 { - docPath = strings.TrimRight(docPath, "/") + "/src/modules/ROOT/pages" + docPath = strings.TrimRight(docPath, "/") + "/src/modules/ROOT" if i, err := os.Stat(docPath); err != nil { handleError(err) } else if !i.IsDir() { @@ -193,7 +193,7 @@ func Proc() { err = genEvents(tpls, eventDefs...) } if genDocs && err == nil { - err = genEventsDocs(tpls, docPath+docPathOptions, eventDefs...) + err = genEventsDocs(tpls, docPath+docGenBase, eventDefs...) } } @@ -237,7 +237,7 @@ func Proc() { } if genDocs && err == nil { - err = genOptionsDocs(tpls, docPath+docPathOptions, optionDefs...) + err = genOptionsDocs(tpls, docPath+docGenBase, optionDefs...) } } diff --git a/pkg/codegen/events.go b/pkg/codegen/events.go index 132d398ee..d2bbec311 100644 --- a/pkg/codegen/events.go +++ b/pkg/codegen/events.go @@ -211,7 +211,7 @@ func genEventsDocs(tpl *template.Template, docsPath string, dd ...*eventsDef) (e dst string ) - dst = path.Join(docsPath, "events_env_variables.gen.adoc") + dst = path.Join(docsPath, "resource-events.gen.adoc") return plainTemplate(dst, tplEventsAdoc, map[string]interface{}{ "Definitions": dd, }) diff --git a/pkg/codegen/options.go b/pkg/codegen/options.go index 090c37dda..ce48f48dc 100644 --- a/pkg/codegen/options.go +++ b/pkg/codegen/options.go @@ -144,7 +144,7 @@ func genOptionsDocs(tpl *template.Template, docsPath string, dd ...*optionsDef) dst string ) - dst = path.Join(docsPath, "option_env_variables_gen.adoc") + dst = path.Join(docsPath, "env-options.gen.adoc") return plainTemplate(dst, tplOptionsAdoc, map[string]interface{}{ "Definitions": dd, }) diff --git a/pkg/options/HTTPClient.yaml b/pkg/options/HTTPClient.yaml index 13e104d8f..16ddbaf2f 100644 --- a/pkg/options/HTTPClient.yaml +++ b/pkg/options/HTTPClient.yaml @@ -9,10 +9,13 @@ props: type: bool env: HTTP_CLIENT_TSL_INSECURE default: false - description: | + description: |- Allow insecure (invalid, expired TSL/SSL certificates) connections. - [IMPORTANT] + + IMPORTANT + ==== We strongly recommend keeping this value set to false except for local development or demos. + ==== - name: httpClientTimeout type: time.Duration diff --git a/pkg/options/SMTP.yaml b/pkg/options/SMTP.yaml index be63596c2..037fa746b 100644 --- a/pkg/options/SMTP.yaml +++ b/pkg/options/SMTP.yaml @@ -1,12 +1,12 @@ docs: title: Email sending - intro: | + intro: |- Configure your local SMTP server or use one of the available providers props: - name: host default: "localhost" - description: | + description: |- The SMTP server hostname. - name: port diff --git a/pkg/options/auth.yaml b/pkg/options/auth.yaml index 14646587e..12d1904ba 100644 --- a/pkg/options/auth.yaml +++ b/pkg/options/auth.yaml @@ -7,15 +7,15 @@ docs: props: - name: secret env: AUTH_JWT_SECRET - description: | + description: |- Secret used for signing JWT tokens. + [IMPORTANT] ==== Make sure to provide a secret. If you don't, a random value is assigned -- this causes all of the tokens to become invalid after a server restart. ==== - - name: expiry type: time.Duration env: AUTH_JWT_EXPIRY diff --git a/pkg/options/sentry.yaml b/pkg/options/sentry.yaml index 8c21d5bf4..eb9892532 100644 --- a/pkg/options/sentry.yaml +++ b/pkg/options/sentry.yaml @@ -3,7 +3,7 @@ imports: docs: title: Sentry monitoring - intro: | + intro: |- [NOTE] ==== These parameters help in the development and testing process. diff --git a/pkg/options/upgrade.yaml b/pkg/options/upgrade.yaml index a4435b1c4..60649551b 100644 --- a/pkg/options/upgrade.yaml +++ b/pkg/options/upgrade.yaml @@ -5,13 +5,12 @@ props: - name: Debug type: bool default: false - description: | + description: |- Enable/disable debug logging. - To enable debug logging set `UPGRADE_DEBUG=true`. + To enable debug logging set `UPGRADE_DEBUG=true`. - name: Always type: bool default: true - description: | - Controls if the upgradable systems should - be upgraded when the server starts. + description: |- + Controls if the upgradable systems should be upgraded when the server starts. diff --git a/pkg/options/waitFor.yaml b/pkg/options/waitFor.yaml index 0cfc8a814..d3c64c394 100644 --- a/pkg/options/waitFor.yaml +++ b/pkg/options/waitFor.yaml @@ -3,7 +3,7 @@ imports: docs: title: Delay system startup - intro: + intro: |- You can configure these options to defer API execution until another external (HTTP) service is up and running. [ TIP ] @@ -11,15 +11,14 @@ docs: Delaying API execution can come in handy in complex setups where execution order is important. ==== - props: - name: Delay type: time.Duration env: WAIT_FOR default: 0 - description: | + description: |- Delays API startup for the amount of time specified (10s, 2m...). - This delay happens before service (`WAIT_FOR_SERVICES`) probing. + This delay happens before service (`WAIT_FOR_SERVICES`) probing. - name: StatusPage type: bool @@ -29,11 +28,14 @@ props: - name: Services env: WAIT_FOR_SERVICES - description: | - Space delimited list of hosts and/or URLs to probe. Host format: `host` or - `host:443` (port will default to 80). + description: |- + Space delimited list of hosts and/or URLs to probe. + Host format: `host` or `host:443` (port will default to 80). + [NOTE] + ==== Services are probed in parallel. + ==== - name: ServicesTimeout type: time.Duration