Options doc codegen tweaks

pkg/codegen/assets/options.gen.adoc.tpl

@@ -8,22 +8,28 @@
 //  - {{ .Source }}
 {{- end }}
 
-= ENV options
 {{ range .Definitions }}
-== {{ .Docs.Title }}
+= {{ .Docs.Title }}
 {{ if .Docs.Intro }}
 {{ .Docs.Intro }}
 {{ end }}
 {{- range .Properties }}
-=== *{{ toUpper .Env }}* `{{ .Type }}`
+== *{{ toUpper .Env }}*
+
+=== Type
+
+`{{ .Type }}`
 
 {{ if or .Default .Description -}}
 {{ if .Default -}}
-Default::
-    `{{ .Default }}`
+=== Default
+
+`{{ .Default }}`
+
 {{ end -}}
 {{ if .Description -}}
-Description::
-    {{ .Description }}
+=== Description
+
+{{ .Description }}
 {{ end -}}{{ end -}}
 {{ end }}{{ end }}

pkg/options/HTTPClient.yaml

@@ -12,7 +12,7 @@ props:
     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.
       ====

pkg/options/provision.yaml

@@ -1,5 +1,16 @@
 docs:
   title: Provisioning
+  intro: |-
+    Provisioning allows you to configure a {PRODUCT_NAME} instance when deployed.
+    It occurs automatically after the {PRODUCT_NAME} server starts.
+
+    [IMPORTANT]
+    ====
+    We recommend you to keep provisioning enabled as it simplifies version updates by updating the database and updating settings.
+
+    If you're doing local development or some debugging, you can disable this.
+    ====
+
 
 props:
   - name: always