feat: Add column renderer templates for all columns

Signed-off-by: GitHub <[email protected]>
norwoodj · Jul 25, 2024 · d2235f4 · d2235f4
1 parent c6e5e3b
commit d2235f4
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 47 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -13,3 +13,6 @@ repos:
           # Repeating the flag adds this to the list, now [./_templates.gotmpl, README.md.gotmpl]
           # A base filename makes it relative to each chart directory found
           - --template-files=README.md.gotmpl
+
+          # For charts with dependencies, include the dependency values in the chart values documentation
+          - --document-dependency-values
diff --git a/README.md b/README.md
@@ -227,36 +227,43 @@ can be used as well:
 
 | Name | Description |
 |------|-------------|
-| chart.header              | The main heading of the generated markdown file |
-| chart.name                | The _name_ field from the chart's `Chart.yaml` file |
-| chart.deprecationWarning  | A deprecation warning which is displayed when the _deprecated_ field from the chart's `Chart.yaml` file is `true` |
-| chart.description         | A description line containing the _description_ field from the chart's `Chart.yaml` file, or "" if that field is not set |
-| chart.version             | The _version_ field from the chart's `Chart.yaml` file |
-| chart.versionBadge        | A badge stating the current version of the chart |
-| chart.type                | The _type_ field from the chart's `Chart.yaml` file |
-| chart.typeBadge           | A badge stating the current type of the chart |
-| chart.appVersion          | The _appVersion_ field from the chart's `Chart.yaml` file |
-| chart.appVersionBadge     | A badge stating the current appVersion of the chart |
-| chart.homepage            | The _home_ link from the chart's `Chart.yaml` file, or "" if that field is not set |
-| chart.homepageLine        | A text line stating the current homepage of the chart |
-| chart.maintainersHeader   | The heading for the chart maintainers section |
-| chart.maintainersTable    | A table of the chart's maintainers |
-| chart.maintainersSection  | A section headed by the maintainersHeader from above containing the maintainersTable from above or "" if there are no maintainers |
-| chart.sourcesHeader       | The heading for the chart sources section |
-| chart.sourcesList         | A list of the chart's sources |
-| chart.sourcesSection      | A section headed by the sourcesHeader from above containing the sourcesList from above or "" if there are no sources |
-| chart.kubeVersion         | The _kubeVersion_ field from the chart's `Chart.yaml` file |
-| chart.kubeVersionLine     | A text line stating the required Kubernetes version for the chart |~~~~
-| chart.requirementsHeader  | The heading for the chart requirements section |
-| chart.requirementsTable   | A table of the chart's required sub-charts |
-| chart.requirementsSection | A section headed by the requirementsHeader from above containing the kubeVersionLine and/or the requirementsTable from above or "" if there are no requirements |
-| chart.valuesHeader        | The heading for the chart values section |
-| chart.valuesTable         | A table of the chart's values parsed from the `values.yaml` file (see below) |
-| chart.valuesSection       | A section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no values |
-| chart.valuesTableHtml     | Like `chart.valuesTable` but it is rendered as (X)HTML tags to allow further rendering customization, instead of markdown tables format. |
-| chart.valuesSectionHtml   | Like `chart.valuesSection` but uses `chart.valuesTableHtml` |
-| chart.valueDefaultColumnRender | This is a hook template if you want to redefine how helm-docs render the default values in `chart.valuesTableHtml` mode. This is especially useful when combined with (X)HTML tags, so that you can nicely format multiline default values, like YAML/JSON object tree snippet with codeblock syntax highlighter, which is not possible or difficult when using the markdown table format. It can be redefined in your template file. |
-| helm-docs.versionFooter   | A footer that contains the version of helm docs being used. |
+| chart.header                         | The main heading of the generated markdown file |
+| chart.name                           | The _name_ field from the chart's `Chart.yaml` file |
+| chart.deprecationWarning             | A deprecation warning which is displayed when the _deprecated_ field from the chart's `Chart.yaml` file is `true` |
+| chart.description                    | A description line containing the _description_ field from the chart's `Chart.yaml` file, or "" if that field is not set |
+| chart.version                        | The _version_ field from the chart's `Chart.yaml` file |
+| chart.versionBadge                   | A badge stating the current version of the chart |
+| chart.type                           | The _type_ field from the chart's `Chart.yaml` file |
+| chart.typeBadge                      | A badge stating the current type of the chart |
+| chart.appVersion                     | The _appVersion_ field from the chart's `Chart.yaml` file |
+| chart.appVersionBadge                | A badge stating the current appVersion of the chart |
+| chart.homepage                       | The _home_ link from the chart's `Chart.yaml` file, or "" if that field is not set |
+| chart.homepageLine                   | A text line stating the current homepage of the chart |
+| chart.maintainersHeader              | The heading for the chart maintainers section |
+| chart.maintainersTable               | A table of the chart's maintainers |
+| chart.maintainersSection             | A section headed by the maintainersHeader from above containing the maintainersTable from above or "" if there are no maintainers |
+| chart.sourcesHeader                  | The heading for the chart sources section |
+| chart.sourcesList                    | A list of the chart's sources |
+| chart.sourcesSection                 | A section headed by the sourcesHeader from above containing the sourcesList from above or "" if there are no sources |
+| chart.kubeVersion                    | The _kubeVersion_ field from the chart's `Chart.yaml` file |
+| chart.kubeVersionLine                | A text line stating the required Kubernetes version for the chart |~~~~
+| chart.requirementsHeader             | The heading for the chart requirements section |
+| chart.requirementsTable              | A table of the chart's required sub-charts |
+| chart.requirementsSection            | A section headed by the requirementsHeader from above containing the kubeVersionLine and/or the requirementsTable from above or "" if there are no requirements |
+| chart.valuesHeader                   | The heading for the chart values section |
+| chart.valuesTableMd                  | A table of the chart's values parsed from the `values.yaml` file (see below) |
+| chart.valuesTable                    | Deprecated. Maps to `chart.valuesTableMd` |
+| chart.valuesSectionMd                | A section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no values |
+| chart.valuesSection                  | Deprecated. Maps to `chart.valuesSectionMd` |
+| chart.valueKeyColumnRenderMd         | This is a hook template if you want to redefine how helm-docs render the key values. |
+| chart.valueTypeColumnRenderMd        | This is a hook template if you want to redefine how helm-docs render the type values. |
+| chart.valueDefaultColumnRenderMd     | This is a hook template if you want to redefine how helm-docs render the default values in `chart.valuesSection` mode. |
+| chart.valueDescriptionColumnRenderMd | This is a hook template if you want to redefine how helm-docs render the description values. |
+| chart.valuesTableHtml                | Like `chart.valuesTableMd` but it is rendered as (X)HTML tags to allow further rendering customization, instead of markdown tables format. |
+| chart.valuesSectionHtml              | Like `chart.valuesSectionMd` but uses `chart.valuesTableHtml` |
+| chart.valueDefaultColumnRenderHtml   | This is a hook template if you want to redefine how helm-docs render the default values in `chart.valuesTableHtml` mode. This is especially useful when combined with (X)HTML tags, so that you can nicely format multiline default values, like YAML/JSON object tree snippet with codeblock syntax highlighter, which is not possible or difficult when using the markdown table format. It can be redefined in your template file. |
+| chart.valueDefaultColumnRender       | Deprecated. Maps to `chart.valueDefaultColumnRenderHtml` |
+| helm-docs.versionFooter              | A footer that contains the version of helm docs being used. |
 
 The default internal template mentioned above uses many of these and looks like this:
 ```

diff --git a/pkg/document/template.go b/pkg/document/template.go
@@ -30,7 +30,7 @@ const defaultDocumentationTemplate = `{{ template "chart.header" . }}
 
 {{ template "chart.requirementsSection" . }}
 
-{{ template "chart.valuesSection" . }}
+{{ template "chart.valuesSectionMd" . }}
 
 {{- if not .SkipVersionFooter }}
 {{ template "helm-docs.versionFooter" . }}
@@ -208,6 +208,22 @@ func getValuesTableTemplates() string {
 	valuesSectionBuilder := strings.Builder{}
 	valuesSectionBuilder.WriteString(`{{ define "chart.valuesHeader" }}## Values{{ end }}`)
 
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueKeyColumnRenderMd" }}`)
+	valuesSectionBuilder.WriteString("{{ .Key }}")
+	valuesSectionBuilder.WriteString("{{ end }}")
+
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueTypeColumnRenderMd" }}`)
+	valuesSectionBuilder.WriteString("{{ .Type }}")
+	valuesSectionBuilder.WriteString("{{ end }}")
+
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueDefaultColumnRenderMd" }}`)
+	valuesSectionBuilder.WriteString("{{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }}")
+	valuesSectionBuilder.WriteString("{{ end }}")
+
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueDescriptionColumnRenderMd" }}`)
+	valuesSectionBuilder.WriteString("{{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }}")
+	valuesSectionBuilder.WriteString("{{ end }}")
+
 	valuesSectionBuilder.WriteString(`{{ define "chart.valuesTable" }}`)
 	valuesSectionBuilder.WriteString("{{ if .Sections.Sections }}")
 	valuesSectionBuilder.WriteString("{{ range .Sections.Sections }}")
@@ -217,7 +233,7 @@ func getValuesTableTemplates() string {
 	valuesSectionBuilder.WriteString("| Key | Type | Default | Description |\n")
 	valuesSectionBuilder.WriteString("|-----|------|---------|-------------|\n")
 	valuesSectionBuilder.WriteString("  {{- range .SectionItems }}")
-	valuesSectionBuilder.WriteString("\n| {{ .Key }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} |")
+	valuesSectionBuilder.WriteString("\n" + `| {{ template "chart.valueKeyColumnRenderMd" . }} | {{ template "chart.valueTypeColumnRenderMd" . }} | {{ template "chart.valueDefaultColumnRenderMd" . }} | {{ template "chart.valueDescriptionColumnRenderMd" . }} |`)
 	valuesSectionBuilder.WriteString("  {{- end }}")
 	valuesSectionBuilder.WriteString("{{- end }}")
 	valuesSectionBuilder.WriteString("{{ if .Sections.DefaultSection.SectionItems}}")
@@ -227,27 +243,49 @@ func getValuesTableTemplates() string {
 	valuesSectionBuilder.WriteString("| Key | Type | Default | Description |\n")
 	valuesSectionBuilder.WriteString("|-----|------|---------|-------------|\n")
 	valuesSectionBuilder.WriteString("  {{- range .Sections.DefaultSection.SectionItems }}")
-	valuesSectionBuilder.WriteString("\n| {{ .Key }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} |")
+	valuesSectionBuilder.WriteString("\n" + `| {{ template "chart.valueKeyColumnRenderMd" . }} | {{ template "chart.valueTypeColumnRenderMd" . }} | {{ template "chart.valueDefaultColumnRenderMd" . }} | {{ template "chart.valueDescriptionColumnRenderMd" . }} |`)
 	valuesSectionBuilder.WriteString("  {{- end }}")
 	valuesSectionBuilder.WriteString("{{ end }}")
 	valuesSectionBuilder.WriteString("{{ else }}")
 	valuesSectionBuilder.WriteString("| Key | Type | Default | Description |\n")
 	valuesSectionBuilder.WriteString("|-----|------|---------|-------------|\n")
 	valuesSectionBuilder.WriteString("  {{- range .Values }}")
-	valuesSectionBuilder.WriteString("\n| {{ .Key }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} |")
+	valuesSectionBuilder.WriteString("\n" + `| {{ template "chart.valueKeyColumnRenderMd" . }} | {{ template "chart.valueTypeColumnRenderMd" . }} | {{ template "chart.valueDefaultColumnRenderMd" . }} | {{ template "chart.valueDescriptionColumnRenderMd" . }} |`)
 	valuesSectionBuilder.WriteString("  {{- end }}")
 	valuesSectionBuilder.WriteString("{{ end }}")
 	valuesSectionBuilder.WriteString("{{ end }}")
 
+	// TODO: Remove this block and rename `chart.valuesTable` to `chart.valuesTableMd` in the future
+	valuesSectionBuilder.WriteString(`{{ define "chart.valuesTableMd" }}`)
+	valuesSectionBuilder.WriteString(`{{ template "chart.valuesTable" . }}`)
+	valuesSectionBuilder.WriteString("{{ end }}")
+
 	valuesSectionBuilder.WriteString(`{{ define "chart.valuesSection" }}`)
 	valuesSectionBuilder.WriteString("{{ if .Values }}")
 	valuesSectionBuilder.WriteString(`{{ template "chart.valuesHeader" . }}`)
 	valuesSectionBuilder.WriteString("\n\n")
-	valuesSectionBuilder.WriteString(`{{ template "chart.valuesTable" . }}`)
+	valuesSectionBuilder.WriteString(`{{ template "chart.valuesTableMd" . }}`)
+	valuesSectionBuilder.WriteString("{{ end }}")
 	valuesSectionBuilder.WriteString("{{ end }}")
+
+	// TODO: Remove this block and rename `chart.valuesTable` to `chart.valuesTableMd` in the future
+	valuesSectionBuilder.WriteString(`{{ define "chart.valuesSectionMd" }}`)
+	valuesSectionBuilder.WriteString(`{{ template "chart.valuesSection" . }}`)
 	valuesSectionBuilder.WriteString("{{ end }}")
 
 	// For HTML tables
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueKeyColumnRenderHtml" }}`)
+	valuesSectionBuilder.WriteString(`{{ template "chart.valueKeyColumnRenderMd" . }}`)
+	valuesSectionBuilder.WriteString("{{ end }}")
+
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueTypeColumnRenderHtml" }}`)
+	valuesSectionBuilder.WriteString(`{{ template "chart.valueTypeColumnRenderMd" . }}`)
+	valuesSectionBuilder.WriteString("{{ end }}")
+
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueDescriptionColumnRenderHtml" }}`)
+	valuesSectionBuilder.WriteString(`{{ template "chart.valueDescriptionColumnRenderMd" . }}`)
+	valuesSectionBuilder.WriteString("{{ end }}")
+
 	valuesSectionBuilder.WriteString(`
 {{ define "chart.valueDefaultColumnRender" }}
 {{- $defaultValue := (default .Default .AutoDefault)  -}}
@@ -280,10 +318,10 @@ func getValuesTableTemplates() string {
 	<tbody>
 	{{- range .SectionItems }}
 		<tr>
-			<td>{{ .Key }}</td>
-			<td>{{ .Type }}</td>
-			<td>{{ template "chart.valueDefaultColumnRender" . }}</td>
-			<td>{{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }}</td>
+			<td>{{ template "chart.valueKeyColumnRenderHtml" . }}</td>
+			<td>{{ template "chart.valueTypeColumnRenderHtml" . }}</td>
+			<td>{{ template "chart.valueDefaultColumnRenderHtml" . }}</td>
+			<td>{{ template "chart.valueDescriptionColumnRenderHtml" . }}</td>
 		</tr>
 	{{- end }}
 	</tbody>
@@ -301,10 +339,10 @@ func getValuesTableTemplates() string {
 	<tbody>
 	{{- range .Sections.DefaultSection.SectionItems }}
 	<tr>
-		<td>{{ .Key }}</td>
-		<td>{{ .Type }}</td>
-		<td>{{ template "chart.valueDefaultColumnRender" . }}</td>
-		<td>{{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }}</td>
+		<td>{{ template "chart.valueKeyColumnRenderHtml" . }}</td>
+		<td>{{ template "chart.valueTypeColumnRenderHtml" . }}</td>
+		<td>{{ template "chart.valueDefaultColumnRenderHtml" . }}</td>
+		<td>{{ template "chart.valueDescriptionColumnRenderHtml" . }}</td>
 	</tr>
 	{{- end }}
 	</tbody>
@@ -321,10 +359,10 @@ func getValuesTableTemplates() string {
 	<tbody>
 	{{- range .Values }}
 		<tr>
-			<td>{{ .Key }}</td>
-			<td>{{ .Type }}</td>
-			<td>{{ template "chart.valueDefaultColumnRender" . }}</td>
-			<td>{{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }}</td>
+			<td>{{ template "chart.valueKeyColumnRenderHtml" . }}</td>
+			<td>{{ template "chart.valueTypeColumnRenderHtml" . }}</td>
+			<td>{{ template "chart.valueDefaultColumnRenderHtml" . }}</td>
+			<td>{{ template "chart.valueDescriptionColumnRenderHtml" . }}</td>
 		</tr>
 	{{- end }}
 	</tbody>
@@ -340,6 +378,11 @@ func getValuesTableTemplates() string {
 {{ end }}
 		`)
 
+	// TODO: Remove this block and rename `chart.valueDefaultColumnRender` to `chart.valueDefaultColumnRenderHtml` in the future
+	valuesSectionBuilder.WriteString(`{{ define "chart.valueDefaultColumnRenderHtml" }}`)
+	valuesSectionBuilder.WriteString(`{{ template "chart.valueDefaultColumnRender" . }}`)
+	valuesSectionBuilder.WriteString("{{ end }}")
+
 	return valuesSectionBuilder.String()
 }