Proposal to add custom notation type

[lucernae]

Hi @norwoodj .

First, I would like to say thanks for this great piece of tool. I can imagine I will use it a lot.

I would like to propose some feature addition that rises from the needs of maintaining my own helm charts.

Background

I managed helm chart recipe where some of the services are needed as dependencies to other charts.
Some chart bootstrap other charts from one single values.yaml file. To support some customization in the chart dependencies, some of the values needs to be clearly defined and interlinked (definition of possible values for chart A may reuse or refer the original definition of values in chart B). To support this kind of use case, I propose the following feature additions:

Proposed features

Support for tpl string

Some dependent chart's values needs to be injected from original chart via Go template string. A value that need a go template string can be like this:

global:
  siteName: 'mysite.org'

awesomeApp:
  enabled: true
  siteUrl: |
    https://{{ .Values.global.sitename }}

When chart was generated, the value awesomeApp.siteUrl is set dynamically at generation time as https://mysite.org. However, currently helm-docs will generate the default value of awesomeApp.siteUrl as a JSON escaped string. This doesn't look easy to understand because it will only be a one line string with some escaped character.

I would like to be able to show the default value as:

siteUrl: |
  https://{{ .Values.global.sitename }}

This way, user understands that the value expects a Go template string.

Support for non JSON default value rendering

In some cases, rendering the escaped JSON values looks very complicated. There is also another reason where I want the user to replace a value with a valid YAML structure, but since the default value is rendered as JSON, it looks misleading.

If the values.yaml looks like this:

parent:
  # -- child description
  child:
    name: "honk"
    age: 13
    hobby: "sleeping"

I want the default value to be rendered in YAML like this for the key parent.child:

name: "honk"
age: 13
hobby: "sleeping"

Support for custom value types

Currently, the value types are recognized directly from the YAML structure.
However in some cases, the value types have a clear defined structure that can be referenced elsewhere. Like k8s docs, other chart, or simple structure like email, URL, filepath, csv etc.

I would like to be able to put my own custom type like this:

# -- (string/email) This is a user email type
email: [email protected]
# -- (string/url) This has to be formatted as URL
url: https://somesite.org

At least these types can be parsed and rendered in the values table.

Support for custom notation types

Even if two values use string, that doesn't mean it should be rendered the same way in the default value column.
In some chart, I can put my own configuration file inside the values.yaml so that it can be included in the configmap.
All of it are string value, but we can improve the rendering to match the language syntax.

I propose we add another annotation: @notationType that can tell you what type of rendering it we should use.

# -- This is string, but should be rendered as python file
# @notationType -- python
djangoSettings: |
  import os
  # something pythony

# -- This is string, but can be rendered as nginx config file
# @notationType -- nginx
nginxConfig: |
  # nginx server block
  server {
    location / {
       # some nginx config
    }
  }

The rendering itself is a separate issue, but I was hoping that the @notationType was parsed first and available inside the template.

Support for more flexible value table rendering

My above use case seems to need the table to be generated directly as HTML tags.
I can do it myself, totally separate from helm-docs, however if this can be merged and supported, it would be good.

Basically the current values table are rendered using Github Markdown, from markdown syntax. But if we can provide HTML tags rendering, this would be possible:

• Default values can be rendered as <pre> tag, multiline. So we can pretty print the default behaviour of rendering the default values as JSON
• There's no way for me to display YAML or Go template string in one line using current markdown table syntax. I had to do it multiline using HTML table tags combined with codefence or <pre> tag directly.
• Specifying id in the <td> or <tr> tag of the value rows can create anchor that can be referenced inside the markdown, or across the page. So my chart A can refer to value documentation at chart B.
• Custom rendering the Type columns, so that it will hyperlinked to the data structure/value structure definition somewhere
• Custom rendering the Default value columns, so that it appropriately consider @notationType and render suitable color syntax or format

I think, we can keep the usual value section in markdown and this HTML tables as separate template definition.

[lucernae]

My draft PR regarding this: #87
Can you please share your opinion on this?

[norwoodj]

Done by #87