Merge pull request #29 from eddycharly/master

Add support for custom default values and doc comment continuation

Author: norwoodj

README.md

@@ -106,10 +106,14 @@ controller:
     # controller.publishService.enabled -- Whether to expose the ingress controller to the public world
     enabled: false
 
-  # controller.replicas -- Number of nginx-ingress pods to load balance between
+  # controller.replicas -- Number of nginx-ingress pods to load balance between.
+  # Do not set this below 2.
   replicas: 2
 ```
 
+Note that comments can continue on the next line. In that case leave out the double dash, and the lines will simply be
+appended with a space in-between.
+
 The following rules are used to determine which values will be added to the values table in the README:
 
 * By default, only _leaf nodes_, that is, fields of type `int`, `string`, `float`, `bool`, empty lists, and empty maps
@@ -169,6 +173,22 @@ controller:
 ```
 This could be useful when wanting to enforce user-defined values for the chart, where there are no sensible defaults.
 
+### Default values/column
+In cases where you do not want to include the default value from `values.yaml`, or where the real default is calculated
+inside the chart, you can change the contents of the column like so:
+
+```yaml
+service:
+  # service.annotations -- Add annotations to the service
+  # @default -- the chart will add some internal annotations automatically
+  annotations: []
+```
+
+The order is important. The name must be spelled just like the column heading. The first comment must be the
+one specifying the key. The "@default" comment must follow.
+
+See [here](./example-charts/custom-template/values.yaml) for an example.
+
 ### Spaces and Dots in keys
 If a key name contains any "." or " " characters, that section of the path must be quoted in description comments e.g.
 

example-charts/custom-template/README.md

@@ -29,7 +29,7 @@ culpa qui officia deserunt mollit anim id est laborum.
 | controller.image.tag | string | `"18.0831"` |  |
 | controller.ingressClass | string | `"nginx"` | Name of the ingress class to route through this controller |
 | controller.name | string | `"controller"` |  |
-| controller.persistentVolumeClaims | list | `[]` | List of persistent volume claims to create |
+| controller.persistentVolumeClaims | list | Use this to override the default value specified here in the file | List of persistent volume claims to create. For very long comments, break them into multiple lines. |
 | controller.podLabels | object | `{}` | The labels to be applied to instances of the controller pod |
 | controller.publishService.enabled | bool | `false` | Whether to expose the ingress controller to the public world |
 | controller.replicas | int | `nil` | Number of nginx-ingress pods to load balance between |

example-charts/custom-template/values.yaml

@@ -4,7 +4,9 @@ controller:
     repository: nginx-ingress-controller
     tag: "18.0831"
 
-  # controller.persistentVolumeClaims -- List of persistent volume claims to create
+  # controller.persistentVolumeClaims -- List of persistent volume claims to create.
+  # For very long comments, break them into multiple lines.
+  # @default -- Use this to override the default value specified here in the file
   persistentVolumeClaims: []
 
   extraVolumes:

pkg/document/values.go

@@ -6,6 +6,8 @@ import (
 	"regexp"
 	"sort"
 	"strings"
+
+	"github.com/norwoodj/helm-docs/pkg/helm"
 )
 
 const (
@@ -61,52 +63,59 @@ func getTypeName(value interface{}) string {
 	return ""
 }
 
-func parseNilValueType(key string, description string) valueRow {
+func parseNilValueType(key string, description helm.ChartValueDescription) valueRow {
 	// Grab whatever's in between the parentheses of the description and treat it as the type
-	t := nilValueTypeRegex.FindString(description)
+	t := nilValueTypeRegex.FindString(description.Description)
 
 	if len(t) > 0 {
 		t = t[1 : len(t)-1]
-		description = description[len(t)+3:]
+		description.Description = description.Description[len(t)+3:]
 	} else {
 		t = stringType
 	}
 
+	if description.Default == "" {
+		description.Default = "`nil`"
+	}
+
 	return valueRow{
 		Key:         key,
 		Type:        t,
-		Default:     "`nil`",
-		Description: description,
+		Default:     description.Default,
+		Description: description.Description,
 	}
 }
 
 func createValueRow(
 	key string,
 	value interface{},
-	description string,
+	description helm.ChartValueDescription,
 ) (valueRow, error) {
 	if value == nil {
 		return parseNilValueType(key, description), nil
 	}
 
-	jsonEncodedValue, err := json.Marshal(value)
-	if err != nil {
-		return valueRow{}, fmt.Errorf("failed to marshal default value for %s to json: %s", key, err)
+	if description.Default == "" {
+		jsonEncodedValue, err := json.Marshal(value)
+		if err != nil {
+			return valueRow{}, fmt.Errorf("failed to marshal default value for %s to json: %s", key, err)
+		}
+
+		description.Default = fmt.Sprintf("`%s`", jsonEncodedValue)
 	}
 
-	defaultValue := fmt.Sprintf("`%s`", jsonEncodedValue)
 	return valueRow{
 		Key:         key,
 		Type:        getTypeName(value),
-		Default:     defaultValue,
-		Description: description,
+		Default:     description.Default,
+		Description: description.Description,
 	}, nil
 }
 
 func createRowsFromField(
 	nextPrefix string,
 	value interface{},
-	keysToDescriptions map[string]string,
+	keysToDescriptions map[string]helm.ChartValueDescription,
 	documentLeafNodes bool,
 ) ([]valueRow, error) {
 	switch value.(type) {
@@ -130,7 +139,7 @@ func createRowsFromField(
 func createValueRowsFromList(
 	prefix string,
 	values []interface{},
-	keysToDescriptions map[string]string,
+	keysToDescriptions map[string]helm.ChartValueDescription,
 	documentLeafNodes bool,
 ) ([]valueRow, error) {
 	description, hasDescription := keysToDescriptions[prefix]
@@ -184,7 +193,7 @@ func createValueRowsFromList(
 func createValueRowsFromObject(
 	prefix string,
 	values map[interface{}]interface{},
-	keysToDescriptions map[string]string,
+	keysToDescriptions map[string]helm.ChartValueDescription,
 	documentLeafNodes bool,
 ) ([]valueRow, error) {
 	description, hasDescription := keysToDescriptions[prefix]