Doc codegen tweaks & cleanup

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 -}}

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 }}

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...)
 				}
 			}
 

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,
 	})

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,
 	})

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

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

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

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.

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.

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