improve formatting of values table

[kd7lxl]

Deeply nested values can cause the values table to grow really wide. The key field is not wrapped by default. Example: https://github.com/cortexproject/cortex-helm-chart/blob/cc9ef3dc/README.md#values

By adding zero-width spaces after the .s in the keys, the browser will wrap long keys when needed. Here's an example, notice the table is much narrower and much more readable:
https://github.com/cortexproject/cortex-helm-chart/blob/f6454e5/README.md#values

[norwoodj]

Hey @kd7lxl I like this change in principle and I'm sorry I hadn't looked at this until now. I have only one concern. I think quoted key components which contain dots should be left alone, e.g. controller.service.annotations."external-dns.alpha.kubernetes.io/hostname". This is a feature of helm-docs, to quote components of keys that contain dots to indicate that each component of the inner key is not nested. I don't think we should allow for splitting lines on these types of keys.

[Silthus]

Could you also, maybe in this PR, fix the formatting of the table when long defaults are used?
Currently the description is completely hidden from the viewport.
Another option would be to add an option to order the table columns to make the description show first.

[denis-ryzhkov]

Another idea to avoid horizontal scrolling of both keys and values:

Created with helm-docs -t README.md.gotmpl using the next template file:

{{- /*
  Copy of `defaultDocumentationTemplate` from
  https://github.com/norwoodj/helm-docs/blob/master/pkg/document/template.go
  with `chart.valuesTable` redefined to avoid horizontal scrolling.
*/}}

{{- define "chart.valuesTable" }}
| Key | Type | Default | Description |
|-----|------|---------|-------------|
  {{- range .Values }}
    {{- "\n| "}}{{ .Key | replace "." "<br>." }}
    {{- " | "}}{{ .Type }}
    {{- " | "}}{{ (default .Default .AutoDefault) | replace "," ",`<br>`" }}
    {{- " | "}}{{ default .Description .AutoDescription }}
    {{- " | "}}
  {{- end }}
{{- end }}

{{- template "chart.header" . }}
{{ template "chart.deprecationWarning" . }}

{{ template "chart.badgesSection" . }}

{{ template "chart.description" . }}

{{ template "chart.homepageLine" . }}

{{ template "chart.maintainersSection" . }}

{{ template "chart.sourcesSection" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}

{{- if not .SkipVersionFooter }}
{{ template "helm-docs.versionFooter" . }}
{{- end }}

[pat-s]

Combining the suggestions from above, I've found the following to be the most helpful template:

{{- define "chart.valuesTable" }}
| Key | Type | Default | Description |
|-----|------|---------|-------------|
  {{- range .Values }}
    {{- "\n| "}}{{ .Key | replace "." ".​" }}
    {{- " | "}}{{ .Type }}
    {{- " | "}}{{ (default .Default .AutoDefault) | replace "," ",`<br>`" }}
    {{- " | "}}{{ default .Description .AutoDescription }}
    {{- " | "}}
  {{- end }}
{{- end }}

This also works great for forges other than GH which have a fixed-width table layout.

Example Forgejo
Example GitHub

Without the addition of | replace "." ".​" for .Key, this columns becomes way to wide and hides others.
Other solutions to break it result in the disability to apply proper page searches as one cannot do section1.section2 anymore due to a non-matching character alignment.

There's still room for improvement, especially for the Default section, as values there can easily get too long (e.g. hashes or regex patterns).

@norwoodj Any interest in patching this for the next version? Seems like a long-standing "issue" which could be improved.

[norwoodj]

I'm not sure how I feel about this still. I like being able to view the markdown in plaintext, and this kinda wrecks that:

 | Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| config.databasesToCreate[0] | string | `"postgresql"` | default database for storage of database metadata |
-| config.databasesToCreate[1] | string | `"hashbash"` | database for the [hashbash](https://github.com/norwoodj/hashbash) project |
-| config.usersToCreate[0] | object | `{"admin":true,"name":"root"}` | admin user |
-| config.usersToCreate[1] | object | `{"name":"hashbash","readwriteDatabases":["hashbash"]}` | user with access to the database with the same name |
-| configWithAllValuesIgnored | object | `{}` |  |
-| statefulset.extraVolumes | list | `[{"emptyDir":{},"name":"data"}]` | Additional volumes to be mounted into the database container |
-| statefulset.image.repository | string | `"jnorwood/postgresq"` | Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files |
-| statefulset.image.tag | string | `"11"` |  |
-| statefulset.livenessProbe | object | `{"enabled":false}` | Configure the healthcheck for the database |
-| statefulset.podLabels | object | `{}` | The labels to be applied to instances of the database |
+|-----|------|---------|-------------|\n| config.​databasesToCreate[0] | string | `"postgresql"` | default database for storage of database metadata |\n| config.​databasesToCreate[1] | string | `"hashbash"` | database for the [hashbash](https://github.com/norwoodj/hashbash) project |\n| config.​usersToCreate[0] | object | `{"admin":true,"name":"root"}` | admin user |\n| config.​usersToCreate[1] | object | `{"name":"hashbash","readwriteDatabases":["hashbash"]}` | user with access to the database with the same name |\n| configWithAllValuesIgnored | object | `{}` |  |\n| statefulset.​extraVolumes | list | `[{"emptyDir":{},"name":"data"}]` | Additional volumes to be mounted into the database container |\n| statefulset.​image.​repository | string | `"jnorwood/postgresq"` | Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files |\n| statefulset.​image.​tag | string | `"11"` |  |\n| statefulset.​livenessProbe | object | `{"enabled":false}` | Configure the healthcheck for the database |\n| statefulset.​podLabels | object | `{}` | The labels to be applied to instances of the database |

[norwoodj]

Reopen this if you fix the issue above and the merge conflicts