Merge pull request #194 from Haepaxlog/sections

Add Support for subsectioned Values

example-charts/sections/Chart.yaml

@@ -0,0 +1,12 @@
+apiVersion: v2
+name: sections
+version: "1.0.0"
+type: application
+appVersion: "13.0.0"
+description: A chart for showing how to use sections
+home: "https://github.com/norwoodj/helm-docs/tree/master/example-charts/sections"
+maintainers:
+  - email: [email protected]
+    name: Constantin Rohde
+sources: ["https://github.com/norwoodj/helm-docs/tree/master/example-charts/sections"]
+engine: gotpl

example-charts/sections/README.md

@@ -0,0 +1,179 @@
+# Sections
+
+This creates values, but sectioned into own section tables if a section comment is provided.
+
+## Values
+
+### Some Section
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| controller.extraVolumes[0].configMap.name | string | `"nginx-ingress-config"` | Uses the name of the configmap created by this chart |
+| controller.persistentVolumeClaims | list | the chart will construct this list internally unless specified | List of persistent volume claims to create. |
+| controller.podLabels | object | `{}` | The labels to be applied to instances of the controller pod |
+
+### Special Attention
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| controller.ingressClass | string | `"nginx"` | You can also specify value comments like this |
+| controller.publishService | object | `{"enabled":false}` | This is a publishService |
+| controller.replicas | int | `nil` | Number of nginx-ingress pods to load balance between |
+
+### Other Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| controller.extraVolumes[0].name | string | `"config-volume"` |  |
+| controller.image.repository | string | `"nginx-ingress-controller"` |  |
+| controller.image.tag | string | `"18.0831"` |  |
+| controller.name | string | `"controller"` |  |
+| controller.service.annotations."external-dns.alpha.kubernetes.io/hostname" | string | `"stupidchess.jmn23.com"` | Hostname to be assigned to the ELB for the service |
+| controller.service.type | string | `"LoadBalancer"` |  |
+
+## Values
+
+<h3>Some Section</h3>
+<table>
+	<thead>
+		<th>Key</th>
+		<th>Type</th>
+		<th>Default</th>
+		<th>Description</th>
+	</thead>
+	<tbody>
+		<tr>
+			<td>controller.extraVolumes[0].configMap.name</td>
+			<td>string</td>
+			<td><pre lang="json">
+"nginx-ingress-config"
+</pre>
+</td>
+			<td>Uses the name of the configmap created by this chart</td>
+		</tr>
+		<tr>
+			<td>controller.persistentVolumeClaims</td>
+			<td>list</td>
+			<td><pre lang="">
+the chart will construct this list internally unless specified
+</pre>
+</td>
+			<td>List of persistent volume claims to create.</td>
+		</tr>
+		<tr>
+			<td>controller.podLabels</td>
+			<td>object</td>
+			<td><pre lang="json">
+{}
+</pre>
+</td>
+			<td>The labels to be applied to instances of the controller pod</td>
+		</tr>
+	</tbody>
+</table>
+<h3>Special Attention</h3>
+<table>
+	<thead>
+		<th>Key</th>
+		<th>Type</th>
+		<th>Default</th>
+		<th>Description</th>
+	</thead>
+	<tbody>
+		<tr>
+			<td>controller.ingressClass</td>
+			<td>string</td>
+			<td><pre lang="json">
+"nginx"
+</pre>
+</td>
+			<td>You can also specify value comments like this</td>
+		</tr>
+		<tr>
+			<td>controller.publishService</td>
+			<td>object</td>
+			<td><pre lang="json">
+{
+  "enabled": false
+}
+</pre>
+</td>
+			<td>This is a publishService</td>
+		</tr>
+		<tr>
+			<td>controller.replicas</td>
+			<td>int</td>
+			<td><pre lang="json">
+null
+</pre>
+</td>
+			<td>Number of nginx-ingress pods to load balance between</td>
+		</tr>
+	</tbody>
+</table>
+
+<h3>Other Values</h3>
+<table>
+	<thead>
+		<th>Key</th>
+		<th>Type</th>
+		<th>Default</th>
+		<th>Description</th>
+	</thead>
+	<tbody>
+	<tr>
+		<td>controller.extraVolumes[0].name</td>
+		<td>string</td>
+		<td><pre lang="json">
+"config-volume"
+</pre>
+</td>
+		<td></td>
+	</tr>
+	<tr>
+		<td>controller.image.repository</td>
+		<td>string</td>
+		<td><pre lang="json">
+"nginx-ingress-controller"
+</pre>
+</td>
+		<td></td>
+	</tr>
+	<tr>
+		<td>controller.image.tag</td>
+		<td>string</td>
+		<td><pre lang="json">
+"18.0831"
+</pre>
+</td>
+		<td></td>
+	</tr>
+	<tr>
+		<td>controller.name</td>
+		<td>string</td>
+		<td><pre lang="json">
+"controller"
+</pre>
+</td>
+		<td></td>
+	</tr>
+	<tr>
+		<td>controller.service.annotations."external-dns.alpha.kubernetes.io/hostname"</td>
+		<td>string</td>
+		<td><pre lang="json">
+"stupidchess.jmn23.com"
+</pre>
+</td>
+		<td>Hostname to be assigned to the ELB for the service</td>
+	</tr>
+	<tr>
+		<td>controller.service.type</td>
+		<td>string</td>
+		<td><pre lang="json">
+"LoadBalancer"
+</pre>
+</td>
+		<td></td>
+	</tr>
+	</tbody>
+</table>

example-charts/sections/README.md.gotmpl

@@ -0,0 +1,7 @@
+# Sections
+
+This creates values, but sectioned into own section tables if a seciton comment is provided.
+
+{{ template "chart.valuesSection" . }}
+
+{{ template "chart.valuesSectionHtml" . }}

example-charts/sections/values.yaml

@@ -0,0 +1,43 @@
+controller:
+  name: controller
+  image:
+    repository: nginx-ingress-controller
+    tag: "18.0831"
+
+  # controller.persistentVolumeClaims -- List of persistent volume claims to create.
+  # @default -- the chart will construct this list internally unless specified
+  # @section -- Some Section
+  persistentVolumeClaims: []
+
+  extraVolumes:
+    - name: config-volume
+      configMap:
+        # controller.extraVolumes[0].configMap.name -- Uses the name of the configmap created by this chart
+        # @section -- Some Section
+        name: nginx-ingress-config
+
+  # -- You can also specify value comments like this
+  # @section -- Special Attention
+  ingressClass: nginx
+
+
+  # controller.podLabels -- The labels to be applied to instances of the controller pod
+  # @section -- Some Section
+  podLabels: {}
+
+  # controller.publishService -- This is a publishService
+  # @section -- Special Attention
+  publishService:
+    enabled: false
+
+  # -- (int) Number of nginx-ingress pods to load balance between
+  # @raw
+  # @section -- Special Attention
+  replicas:
+
+  service:
+    annotations:
+      # controller.service.annotations."external-dns.alpha.kubernetes.io/hostname" -- Hostname to be assigned to the ELB for the service
+      external-dns.alpha.kubernetes.io/hostname: stupidchess.jmn23.com
+
+    type: LoadBalancer

pkg/document/model.go

@@ -20,6 +20,7 @@ type valueRow struct {
 	Default         string
 	AutoDescription string
 	Description     string
+	Section         string
 	Column          int
 	LineNumber      int
 	Dependency      string
@@ -30,17 +31,21 @@ type chartTemplateData struct {
 	helm.ChartDocumentationInfo
 	HelmDocsVersion string
 	Values          []valueRow
+	Sections        sections
 	Files           files
 }
 
-func sortValueRows(valueRows []valueRow) {
-	sortOrder := viper.GetString("sort-values-order")
+type sections struct {
+	DefaultSection section
+	Sections       []section
+}
 
-	if sortOrder != FileSortOrder && sortOrder != AlphaNumSortOrder {
-		log.Warnf("Invalid sort order provided %s, defaulting to %s", sortOrder, AlphaNumSortOrder)
-		sortOrder = AlphaNumSortOrder
-	}
+type section struct {
+	SectionName  string
+	SectionItems []valueRow
+}
 
+func sortValueRowsByOrder(valueRows []valueRow, sortOrder string) {
 	sort.Slice(valueRows, func(i, j int) bool {
 		// Globals sort above non-globals.
 		if valueRows[i].IsGlobal != valueRows[j].IsGlobal {
@@ -75,6 +80,32 @@ func sortValueRows(valueRows []valueRow) {
 	})
 }
 
+func sortValueRows(valueRows []valueRow) {
+	sortOrder := viper.GetString("sort-values-order")
+
+	if sortOrder != FileSortOrder && sortOrder != AlphaNumSortOrder {
+		log.Warnf("Invalid sort order provided %s, defaulting to %s", sortOrder, AlphaNumSortOrder)
+		sortOrder = AlphaNumSortOrder
+	}
+
+	sortValueRowsByOrder(valueRows, sortOrder)
+}
+
+func sortSectionedValueRows(sectionedValueRows sections) {
+	sortOrder := viper.GetString("sort-values-order")
+
+	if sortOrder != FileSortOrder && sortOrder != AlphaNumSortOrder {
+		log.Warnf("Invalid sort order provided %s, defaulting to %s", sortOrder, AlphaNumSortOrder)
+		sortOrder = AlphaNumSortOrder
+	}
+
+	sortValueRowsByOrder(sectionedValueRows.DefaultSection.SectionItems, sortOrder)
+
+	for _, section := range sectionedValueRows.Sections {
+		sortValueRowsByOrder(section.SectionItems, sortOrder)
+	}
+}
+
 func getUnsortedValueRows(document *yaml.Node, descriptions map[string]helm.ChartValueDescription) ([]valueRow, error) {
 	// Handle empty values file case.
 	if document.Kind == 0 {
@@ -92,6 +123,39 @@ func getUnsortedValueRows(document *yaml.Node, descriptions map[string]helm.Char
 	return createValueRowsFromField("", nil, document.Content[0], descriptions, true)
 }
 
+func getSectionedValueRows(valueRows []valueRow) sections {
+	var valueRowsSectionSorted sections
+	valueRowsSectionSorted.DefaultSection = section{
+		SectionName:  "Other Values",
+		SectionItems: []valueRow{},
+	}
+
+	for _, row := range valueRows {
+		if row.Section == "" {
+			valueRowsSectionSorted.DefaultSection.SectionItems = append(valueRowsSectionSorted.DefaultSection.SectionItems, row)
+			continue
+		}
+
+		containsSection := false
+		for i, section := range valueRowsSectionSorted.Sections {
+			if section.SectionName == row.Section {
+				containsSection = true
+				valueRowsSectionSorted.Sections[i].SectionItems = append(valueRowsSectionSorted.Sections[i].SectionItems, row)
+				break
+			}
+		}
+
+		if !containsSection {
+			valueRowsSectionSorted.Sections = append(valueRowsSectionSorted.Sections, section{
+				SectionName:  row.Section,
+				SectionItems: []valueRow{row},
+			})
+		}
+	}
+
+	return valueRowsSectionSorted
+}
+
 func getChartTemplateData(info helm.ChartDocumentationInfo, helmDocsVersion string, dependencyValues []DependencyValues) (chartTemplateData, error) {
 	valuesTableRows, err := getUnsortedValueRows(info.ChartValues, info.ChartValuesDescriptions)
 	if err != nil {
@@ -135,6 +199,8 @@ func getChartTemplateData(info helm.ChartDocumentationInfo, helmDocsVersion stri
 	}
 
 	sortValueRows(valuesTableRows)
+	valueRowsSectionSorted := getSectionedValueRows(valuesTableRows)
+	sortSectionedValueRows(valueRowsSectionSorted)
 
 	files, err := getFiles(info.ChartDirectory)
 	if err != nil {
@@ -145,6 +211,7 @@ func getChartTemplateData(info helm.ChartDocumentationInfo, helmDocsVersion stri
 		ChartDocumentationInfo: info,
 		HelmDocsVersion:        helmDocsVersion,
 		Values:                 valuesTableRows,
+		Sections:               valueRowsSectionSorted,
 		Files:                  files,
 	}, nil
 }