Helm-Toolkit: add doc comments to many util functions

This PS adds documentation comments to may of the utility functions
in helm-toolkit.

Change-Id: Id0481284058678ea2834edf462fa7666e429bd79
Signed-off-by: Pete Birley <pete@port.direct>

helm-toolkit/templates/utils/_joinListWithComma.tpl

@@ -14,6 +14,19 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
+{{/*
+abstract: |
+  Joins a list of values into a comma seperated string
+values: |
+  test:
+    - foo
+    - bar
+usage: |
+  {{ include "helm-toolkit.utils.joinListWithComma" .Values.test }}
+return: |
+  foo,bar
+*/}}
+
 {{- define "helm-toolkit.utils.joinListWithComma" -}}
 {{- $local := dict "first" true -}}
 {{- range $k, $v := . -}}{{- if not $local.first -}},{{- end -}}{{- $v -}}{{- $_ := set $local "first" false -}}{{- end -}}

helm-toolkit/templates/utils/_joinListWithSpace.tpl

@@ -14,6 +14,19 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
+{{/*
+abstract: |
+  Joins a list of values into a space seperated string
+values: |
+  test:
+    - foo
+    - bar
+usage: |
+  {{ include "helm-toolkit.utils.joinListWithSpace" .Values.test }}
+return: |
+  foo bar
+*/}}
+
 {{- define "helm-toolkit.utils.joinListWithSpace" -}}
 {{- $local := dict "first" true -}}
 {{- range $k, $v := . -}}{{- if not $local.first -}}{{- " " -}}{{- end -}}{{- $v -}}{{- $_ := set $local "first" false -}}{{- end -}}

helm-toolkit/templates/utils/_merge.tpl

@@ -28,6 +28,7 @@ to the target key. Slices are merged by appending them and removing any
 duplicates. Any other values are merged by simply keeping the source, and
 throwing away the target.
 */}}
+
 {{- define "helm-toolkit.utils.merge" -}}
   {{- $local := dict -}}
   {{- if kindIs "map" $ -}}

helm-toolkit/templates/utils/_to_ini.tpl

@@ -14,6 +14,29 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
+{{/*
+abstract: |
+  Returns INI formatted output from yaml input
+values: |
+  conf:
+    paste:
+      filter:debug:
+        use: egg:oslo.middleware#debug
+      filter:request_id:
+        use: egg:oslo.middleware#request_id
+      filter:build_auth_context:
+        use: egg:keystone#build_auth_context
+usage: |
+  {{ include "helm-toolkit.utils.to_ini" .Values.conf.paste }}
+return: |
+  [filter:build_auth_context]
+  use = egg:keystone#build_auth_context
+  [filter:debug]
+  use = egg:oslo.middleware#debug
+  [filter:request_id]
+  use = egg:oslo.middleware#request_id
+*/}}
+
 {{- define "helm-toolkit.utils.to_ini" -}}
 {{- range $section, $values := . -}}
 {{- if kindIs "map" $values -}}

helm-toolkit/templates/utils/_to_k8s_env_vars.tpl

@@ -14,6 +14,20 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
+{{/*
+abstract: |
+  Returns key value pair formatted to be used in k8s templates as container
+  env vars.
+values: |
+  test:
+    foo: bar
+usage: |
+  {{ include "helm-toolkit.utils.to_k8s_env_vars" .Values.test }}
+return: |
+  - name: foo
+    value: "bar"
+*/}}
+
 {{- define "helm-toolkit.utils.to_k8s_env_vars" -}}
 {{range $key, $value := . -}}
 {{- if kindIs "slice" $value -}}

helm-toolkit/templates/utils/_to_kv_list.tpl

@@ -14,16 +14,18 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns key value pair in the INI format (key = value)
-# as needed by openstack config files
-#
-# Sample key value pair format:
-# conf:
-#   libvirt:
-#     log_level: 3
-# Usage:
-# { include "helm-toolkit.utils.to_kv_list" .Values.conf.libvirt }
-# returns: log_level = 3
+{{/*
+abstract: |
+  Returns key value pair in INI format (key = value)
+values: |
+  conf:
+    libvirt:
+      log_level: 3
+usage: |
+  {{ include "helm-toolkit.utils.to_kv_list" .Values.conf.libvirt }}
+return: |
+  log_level = 3
+*/}}
 
 {{- define "helm-toolkit.utils.to_kv_list" -}}
 {{- range $key, $value :=  . -}}

helm-toolkit/templates/utils/_to_oslo_conf.tpl

@@ -14,6 +14,37 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
+{{/*
+abstract: |
+  Returns OSLO.conf formatted output from yaml input
+values: |
+  conf:
+    keystone:
+      DEFAULT: # Keys at this level are used for section headings
+        max_token_size: 255
+      oslo_messaging_notifications:
+        driver: # An example of a multistring option's syntax
+          type: multistring
+          values:
+            - messagingv2
+            - log
+      security_compliance:
+        password_expires_ignore_user_ids:
+        # Values in a list will be converted to a comma separated key
+          - "123"
+          - "456"
+usage: |
+  {{ include "helm-toolkit.utils.to_oslo_conf" .Values.conf.keystone }}
+return: |
+  [DEFAULT]
+  max_token_size = 255
+  [oslo_messaging_notifications]
+  driver = messagingv2
+  driver = log
+  [security_compliance]
+  password_expires_ignore_user_ids = 123,456
+*/}}
+
 {{- define "helm-toolkit.utils.to_oslo_conf" -}}
 {{- range $section, $values := . -}}
 {{- if kindIs "map" $values -}}

helm-toolkit/templates/utils/_values_template_renderer.tpl

@@ -15,26 +15,26 @@ limitations under the License.
 */}}
 
 {{/*
-This function renders out configuration sections into a format suitable for
-incorporation into a config-map. This allows various forms of input to be
-rendered out as appropriate, as illustrated in the following example:
-
-With the input:
-
+abstract: |
+  Renders out configuration sections into a format suitable for incorporation
+  into a config-map. Allowing various forms of input to be rendered out as
+  appropriate.
+values: |
   conf:
+    inputs:
+      - foo
+      - bar
     some:
       config_to_render: |
         #We can use all of gotpl here: eg macros, ranges etc.
-        Listen 0.0.0.0:{{ tuple "dashboard" "internal" "web" . | include "helm-toolkit.endpoints.endpoint_port_lookup" }}
+        {{ include "helm-toolkit.utils.joinListWithComma" .Values.conf.inputs }}
       config_to_complete:
         #here we can fill out params, but things need to be valid yaml as input
         '{{ .Release.Name }}': '{{ printf "%s-%s" .Release.Namespace "namespace" }}'
       static_config:
         #this is just passed though as yaml to the configmap
         foo: bar
-
-And the template:
-
+usage: |
   {{- $envAll := . }}
   ---
   apiVersion: v1
@@ -45,9 +45,8 @@ And the template:
   {{- include "helm-toolkit.snippets.values_template_renderer" (dict "envAll" $envAll "template" .Values.conf.some.config_to_render "key" "config_to_render.conf") | indent 2 }}
   {{- include "helm-toolkit.snippets.values_template_renderer" (dict "envAll" $envAll "template" .Values.conf.some.config_to_complete "key" "config_to_complete.yaml") | indent 2 }}
   {{- include "helm-toolkit.snippets.values_template_renderer" (dict "envAll" $envAll "template" .Values.conf.some.static_config "key" "static_config.yaml") | indent 2 }}
-
-The rendered output will match:
-
+return: |
+  ---
   apiVersion: v1
   kind: ConfigMap
   metadata:
@@ -55,14 +54,13 @@ The rendered output will match:
   data:
     config_to_render.conf: |
       #We can use all of gotpl here: eg macros, ranges etc.
-      Listen 0.0.0.0:80
+      foo,bar
 
     config_to_complete.yaml: |
       'RELEASE-NAME': 'default-namespace'
 
     static_config.yaml: |
       foo: bar
-
 */}}
 
 {{- define "helm-toolkit.snippets.values_template_renderer" -}}