recursive doc generation

Author: d-rk

cmd/cmd.go

@@ -9,6 +9,7 @@ import (
 	"github.com/random-dwi/helm-doc/writer"
 	"github.com/spf13/cobra"
 	"k8s.io/helm/pkg/chartutil"
+	"k8s.io/helm/pkg/proto/hapi/chart"
 	"log"
 	"os"
 )
@@ -59,7 +60,7 @@ func init() {
 
 func run(cmd *cobra.Command, args []string) error {
 	if len(args) < 1 {
-		return errors.New("chart is required")
+		return errors.New("c is required")
 	}
 
 	if flags.Verbose {
@@ -68,7 +69,7 @@ func run(cmd *cobra.Command, args []string) error {
 
 	output.Debugf("helm home: %s", os.Getenv("HELM_HOME"))
 
-	output.Debugf("Original chart version: %q", flags.Version)
+	output.Debugf("Original c version: %q", flags.Version)
 	if flags.Version == "" && flags.Devel {
 		output.Debugf("setting version to >0.0.0-0")
 		flags.Version = ">0.0.0-0"
@@ -90,37 +91,42 @@ func run(cmd *cobra.Command, args []string) error {
 
 	var gen writer.DocumentationWriter = writer.NewMarkdownWriter(os.Stdout)
 
+	parentCharts := make(map[*chart.Chart]*chart.Chart)
+	writeChartDocs(c, 1, gen, parentCharts, nil)
+
+	return nil
+}
+
+func writeChartDocs(chart *chart.Chart, layer int, gen writer.DocumentationWriter, parentCharts map[*chart.Chart]*chart.Chart, parent *chart.Chart) {
+
 	var dependencyNames []string
 
-	for _, dependency := range c.Dependencies {
+	for _, dependency := range chart.Dependencies {
 		dependencyNames = append(dependencyNames, dependency.Metadata.Name)
 	}
 
-	output.Debugf("generating docs for %s:%s", c.Metadata.Name, c.Metadata.Version)
-	docs, err := generator.GenerateDocs(c, dependencyNames, flags)
+	parentCharts[chart] = parent
 
-	gen.WriteMetaData(c.Metadata, 1)
-	gen.WriteDocs(docs)
+	output.Debugf("generating docs for %s:%s", chart.Metadata.Name, chart.Metadata.Version)
+	docs, err := generator.GenerateDocs(chart, dependencyNames, parentCharts, flags)
 
-	if len(c.Dependencies) > 0 {
-		gen.WriteChapter("Dependencies", 2)
+	if err != nil {
+		if parent == nil || flags.VerifyDependencies {
+			output.Failf("%v", err)
+		} else {
+			output.Warnf("%v", err)
+		}
 	}
 
-	for _, dependency := range c.Dependencies {
-		output.Debugf("generating docs for %s:%s", dependency.Metadata.Name, dependency.Metadata.Version)
-		docs, err := generator.GenerateDocs(dependency, nil, flags)
+	gen.WriteMetaData(chart.Metadata, layer)
+	gen.WriteDocs(docs)
 
-		if err != nil {
-			if flags.VerifyDependencies {
-				output.Failf("%v", err)
-			} else {
-				output.Warnf("%v", err)
-			}
-		} else {
-			gen.WriteMetaData(dependency.Metadata, 3)
-			gen.WriteDocs(docs)
+	if len(chart.Dependencies) > 0 {
+		layer++
+		gen.WriteChapter("Dependencies", layer)
+		layer++
+		for _, dependency := range chart.Dependencies {
+			writeChartDocs(dependency, layer, gen, parentCharts, chart)
 		}
 	}
-
-	return nil
 }

generator/doc_generator.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"github.com/ghodss/yaml"
 	"github.com/golang/protobuf/ptypes/any"
+	"github.com/random-dwi/helm-doc/helm"
 	"github.com/random-dwi/helm-doc/output"
 	"k8s.io/helm/pkg/proto/hapi/chart"
 	"regexp"
@@ -33,54 +34,85 @@ type ConfigDoc struct {
 	ExampleValue interface{}
 }
 
-func GenerateDocs(chart *chart.Chart, ignoredPrefixes []string, flags CommandFlags) (map[string]*ConfigDoc, error) {
+func GenerateDocs(c *chart.Chart, ignoredPrefixes []string, parentCharts map[*chart.Chart]*chart.Chart, flags CommandFlags) (map[string]*ConfigDoc, error) {
 
-	values, err := parseYaml([]byte(chart.Values.Raw))
+	var allValues = make(map[string]map[string]interface{})
+	var valueSource []string
 
-	if err != nil {
-		return nil, fmt.Errorf("unable to read values for %s:%s: %v", chart.Metadata.Name, chart.Metadata.Version, err)
+	var currentChart = c
+	var currentPrefix = ""
+
+	for currentChart != nil {
+		valueSource = append(valueSource, currentChart.Metadata.Name)
+
+		var rawValues []byte
+		if currentChart.Values == nil {
+			output.Debugf("chart has no values.yaml")
+			rawValues = []byte("")
+		} else {
+			rawValues = []byte(currentChart.Values.Raw)
+		}
+
+		values, err := parseYaml(rawValues)
+
+		if err != nil {
+			return nil, fmt.Errorf("unable to read values for %s:%s: %v", currentChart.Metadata.Name, currentChart.Metadata.Version, err)
+		}
+
+		if currentPrefix != "" {
+			val := findValueForKeyAndGlobal(currentPrefix, values, values["global"])
+			values, _ = val.(map[string]interface{})
+			currentPrefix = currentChart.Metadata.Name + "." + currentPrefix
+		} else {
+			currentPrefix = currentChart.Metadata.Name
+		}
+
+		allValues[currentChart.Metadata.Name] = values
+		currentChart = parentCharts[currentChart]
 	}
 
-	definitions, err := findAndParseYaml(chart.Files, "definitions.yaml")
+	definitions, err := findAndParseYaml(c.Files, "definitions.yaml")
 
 	if err != nil {
-		return nil, fmt.Errorf("unable to read definitions for %s:%s: %v", chart.Metadata.Name, chart.Metadata.Version, err)
+		return nil, fmt.Errorf("unable to read definitions for %s:%s: %v", c.Metadata.Name, c.Metadata.Version, err)
 	}
 
-	examples, err := findAndParseYaml(chart.Files, "examples.yaml")
+	examples, err := findAndParseYaml(c.Files, "examples.yaml")
 
 	if err != nil {
 		if flags.VerifyExamples {
-			return nil, fmt.Errorf("unable to read examples for %s:%s: %v", chart.Metadata.Name, chart.Metadata.Version, err)
+			return nil, fmt.Errorf("unable to read examples for %s:%s: %v", c.Metadata.Name, c.Metadata.Version, err)
 		} else {
-			output.Warnf("unable to read examples for %s:%s: %v", chart.Metadata.Name, chart.Metadata.Version, err)
+			output.Warnf("unable to read examples for %s:%s: %v", c.Metadata.Name, c.Metadata.Version, err)
 		}
 	}
 
-	return generate(definitions, values, examples, ignoredPrefixes, flags), nil
+	return generate(definitions, allValues, valueSource, examples, ignoredPrefixes, flags), nil
 }
 
-func generate(definitions map[string]interface{}, values map[string]interface{}, examples map[string]interface{}, ignoredPrefixes []string, flags CommandFlags) map[string]*ConfigDoc {
+func generate(definitions map[string]interface{}, allValues map[string]map[string]interface{}, valueSource []string, examples map[string]interface{}, ignoredPrefixes []string, flags CommandFlags) map[string]*ConfigDoc {
 
 	docs := convertToConfigDocs("", definitions)
 
 	if len(ignoredPrefixes) > 0 {
-		for key := range values {
-			if containsString(ignoredPrefixes, key) {
-				delete(values, key)
+		for _, source := range valueSource {
+			for key := range allValues[source] {
+				if containsString(ignoredPrefixes, key) {
+					delete(allValues[source], key)
+				}
 			}
 		}
 	}
 
 	if flags.VerifyValues {
-		missingKeys := validateDefaultValues("", definitions, values)
+		missingKeys := validateDefaultValues("", definitions, allValues[valueSource[0]])
 		if len(missingKeys) > 0 {
 			var prefix = "\n\t"
 			output.Failf("undocumented values detected: %s%s", prefix, strings.Join(missingKeys, prefix))
 		}
 	}
 
-	docs = insertDefaultValues(docs, values)
+	docs = insertDefaultValues(docs, allValues, valueSource)
 
 	if examples != nil {
 		docs = insertExampleValues(docs, examples, flags)
@@ -184,15 +216,34 @@ func validateDefaultValues(parentKey string, definitions map[string]interface{},
 	return missingKeys
 }
 
-func insertDefaultValues(docs map[string]*ConfigDoc, values map[string]interface{}) map[string]*ConfigDoc {
+func insertDefaultValues(docs map[string]*ConfigDoc, allValues map[string]map[string]interface{}, valueSource []string) map[string]*ConfigDoc {
 
 	for globalKey, configDoc := range docs {
-		configDoc.DefaultValue = findValueForKey(globalKey, values, false)
+		var defaultValue interface{} = nil
+		for _, source := range valueSource {
+			defaultValue = mergeValues(findValueForKey(globalKey, allValues[source], false), defaultValue)
+		}
+		configDoc.DefaultValue = defaultValue
 	}
 
 	return docs
 }
 
+func mergeValues(defaultParent interface{}, defaultChild interface{}) interface{} {
+	parentMap, parentIsMap := defaultParent.(map[string]interface{})
+	childMap, childIsMap := defaultChild.(map[string]interface{})
+	if !parentIsMap || !childIsMap {
+		// parent overwrites child
+		if defaultParent != nil {
+			return defaultParent
+		} else {
+			return defaultChild
+		}
+	} else {
+		return helm.MergeValues(childMap, parentMap)
+	}
+}
+
 func insertExampleValues(docs map[string]*ConfigDoc, examples map[string]interface{}, flags CommandFlags) map[string]*ConfigDoc {
 
 	var missingExamples []string
@@ -206,7 +257,7 @@ func insertExampleValues(docs map[string]*ConfigDoc, examples map[string]interfa
 
 	if missingExamples != nil {
 		var prefix = "\n\t"
-		output.Failf("when --force-examples is true an example needs to be provided for every config without default: %s%s", prefix, strings.Join(missingExamples, prefix))
+		output.Failf("when --verify-examples is true an example needs to be provided for every config without default: %s%s", prefix, strings.Join(missingExamples, prefix))
 	}
 
 	return docs
@@ -257,6 +308,36 @@ func findDefinitionForKeyOrParentKey(globalKey string, definitions map[string]in
 	return false
 }
 
+func findValueForKeyAndGlobal(globalKey string, values map[string]interface{}, global interface{}) interface{} {
+
+	keys := strings.Split(globalKey, ".")
+
+	for i := range keys {
+		leftMostKeys := keys[:len(keys)-i]
+		joinedKey := strings.Join(leftMostKeys, ".")
+
+		if subValues, exists := values[joinedKey]; exists {
+			subKey := strings.TrimPrefix(strings.TrimPrefix(globalKey, joinedKey), ".")
+
+			newMap, isMap := subValues.(map[string]interface{})
+			if isMap {
+				if subKey == "" {
+					newMap["global"] = global
+					return newMap
+				} else {
+					return findValueForKeyAndGlobal(subKey, newMap, global)
+				}
+			} else {
+				globalMap := make(map[string]interface{})
+				globalMap["global"] = global
+				return globalMap
+			}
+		}
+	}
+
+	return nil
+}
+
 // find value for a given key or nil if it does not exist
 // if `useParentValue` is true, instead of nil the parent value is returned if available
 func findValueForKey(globalKey string, values map[string]interface{}, useParentValue bool) interface{} {

generator/doc_generator_test.go

@@ -70,6 +70,31 @@ func Test_findValueForKey(t *testing.T) {
 	}
 }
 
+func Test_mergeValues(t *testing.T) {
+	type args struct {
+		defaultParent interface{}
+		defaultChild  interface{}
+	}
+	tests := []struct {
+		name string
+		args args
+		want interface{}
+	}{
+		{name: "test_parent_nil", args: args{defaultParent: nil, defaultChild: parseJson(`{"global": "child"}`)}, want: parseJson(`{"global": "child"}`)},
+		{name: "test_string_merge", args: args{defaultParent: parseJson(`{"global": "parent"}`), defaultChild: parseJson(`{"global": "child"}`)}, want: parseJson(`{"global": "parent"}`)},
+		{name: "test_string_overwrite", args: args{defaultParent: `"global"`, defaultChild: parseJson(`{"global": "child"}`)}, want: `"global"`},
+		{name: "test_map_overwrite", args: args{defaultParent: parseJson(`{"global": "parent"}`), defaultChild: `"somestring"`}, want: parseJson(`{"global": "parent"}`)},
+		{name: "test_map_merge", args: args{defaultParent: parseJson(`{"global": {"hello": "parent"}}`), defaultChild: parseJson(`{"global": {"hello": "child", "other": "value"}}`)}, want: parseJson(`{"global": {"hello": "parent", "other": "value"}}`)},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := mergeValues(tt.args.defaultParent, tt.args.defaultChild); !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("mergeValues() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
 func parseJson(value string) map[string]interface{} {
 	valueMap := map[string]interface{}{}
 

helm/helm.go

@@ -97,3 +97,35 @@ func LocateChartPath(repoURL, username, password, name, version string, verify b
 
 	return filename, fmt.Errorf("failed to download %q (hint: running `helm repo update` may help)", name)
 }
+
+// Copied from Helm.
+func MergeValues(dest map[string]interface{}, src map[string]interface{}) map[string]interface{} {
+	for k, v := range src {
+		// If the key doesn't exist already, then just set the key to that value
+		if _, exists := dest[k]; !exists {
+			dest[k] = v
+			continue
+		}
+		nextMap, ok := v.(map[string]interface{})
+		// If it isn't another map, overwrite the value
+		if !ok {
+			dest[k] = v
+			continue
+		}
+		// If the key doesn't exist already, then just set the key to that value
+		if _, exists := dest[k]; !exists {
+			dest[k] = nextMap
+			continue
+		}
+		// Edge case: If the key exists in the destination, but isn't a map
+		destMap, isMap := dest[k].(map[string]interface{})
+		// If the source map has a map for this key, prefer it
+		if !isMap {
+			dest[k] = v
+			continue
+		}
+		// If we got to this point, it is a map in both, so merge them
+		dest[k] = MergeValues(destMap, nextMap)
+	}
+	return dest
+}

install_plugin_dev.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+helm plugin remove doc
+rm `helm home`/plugins/helm-doc
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+ln -s $DIR `helm home`/plugins/helm-doc
+echo "created symlink to `helm home`/plugins/helm-doc"

link.sh

@@ -36,13 +36,17 @@ func (g MarkdownWriter) WriteMetaData(metaData *chart.Metadata, layer int) {
 	}
 
 	g.fprintf(" %s\n\n", metaData.Name)
-	g.fprintf("- **Version:** %s\n\n", metaData.Version)
+	g.fprintf("- **Version:** %s\n", metaData.Version)
 	g.fprintf("- **Description:** %s\n", metaData.Description)
 	g.fprintf("\n")
 }
 
 func (g MarkdownWriter) WriteDocs(docs map[string]*generator.ConfigDoc) {
 
+	if len(docs) == 0 {
+		return
+	}
+
 	g.fprintf("|%s|%s|%s|%s|\n", "KEY", "DESCRIPTION", "DEFAULT", "EXAMPLE")
 	g.fprintf("|---|---|---|---|\n")
 
@@ -58,6 +62,7 @@ func (g MarkdownWriter) WriteDocs(docs map[string]*generator.ConfigDoc) {
 		row := []string{"`" + key + "`", sanitize(configDoc.Description), toMarkdown(configDoc.DefaultValue), toMarkdown(configDoc.ExampleValue)}
 		g.fprintf("|%s|\n", strings.Join(row, "|"))
 	}
+	g.fprintf("\n")
 }
 
 func toMarkdown(object interface{}) string {