feat: updates to add chart search path flag and to search for templat…

…e files differently based on how they're presented fixes #47

.pre-commit-config.yaml

@@ -3,3 +3,8 @@ repos:
     rev: v0.8.0
     hooks:
       - id: helm-docs
+        args:
+          - --chart-search-root=example-charts
+          - --template-files=./_templates.gotmpl
+          - --template-files=README.gotmpl
+          - --log-level=debug

README.md

@@ -107,17 +107,26 @@ when searching for charts. Directories specified need not be charts themselves,
 many charts can be ignored and none of the charts underneath them will be processed. You may also directly reference the
 Chart.yaml file for a chart to skip processing for it.
 
-
 ## Markdown Rendering
-The helm-docs tool uses go-templates to render output documentation. There are a number of sub-templates that are
-referenced in the internal default template and can be used by custom `README.md.gotmpl` templates your repository provides as well.
+There are two important paramaters to be aware of when running helm-docs. `--chart-serach-root` specifies the directory
+under which the tool will recursively search for charts to render documentation for. `--template-files` specifies the list
+of gotemplate files that should be used in rendering the resulting markdown file for each chart found. By default
+`--chart-search-root=.` and `--template-files=README.md.gotmpl`.
 
-Templates can be invoked like so:
-```
-{{ template "template-name" . }}
-```
+If a template file is specified as a filename only as with the default above, the file is interpreted as being _relative to each chart directory found_.
+If however a template file is specified as a relative path, e.g. the first of `--template-files=./_templates.gotmpl --template-files=README.md.gotmpl`
+then the file is interpreted as being relative to the `chart-search-root`.
+
+This repo is a good example of this in action. If you take a look at the [.pre-commit-config.yaml file](./.pre-commit-config.yaml)
+here, you'll see our search root is set to [example-charts](./example-charts) and the list of templates used for each chart
+is the [_templates.gotmpl file in that directory](./example-charts/_templates.gotmpl) and the README.md.gotmpl file in
+each chart directory.
 
-And the complete listing of available templates is below:
+If any of the specified template files is not found for a chart (you'll notice most of the example charts do not have a README.md.gotmpl)
+file, then the internal default template is used instead.
+
+In addition to extra defined templates you specify in these template files, there are quite a few built-in templates that
+can be used as well:
 
 | Name | Description |
 |------|-------------|
@@ -148,11 +157,7 @@ And the complete listing of available templates is below:
 | 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 |
 
-For an example of how these various templates can be used in a `README.md.gotmpl` file to generate a reasonable markdown file,
-look at the charts in [example-charts](./example-charts).
-
-If there is no `README.md.gotmpl` (or other specified gotmpl file) present, the default template is used to generate the README.
-That template looks like so:
+The default internal template mentioned above uses many of these and looks like this:
 ```
 {{ template "chart.header" . }}
 {{ template "chart.deprecationWarning" . }}
@@ -172,10 +177,9 @@ That template looks like so:
 {{ template "chart.valuesSection" . }}
 ```
 
-The tool includes the [sprig templating library](https://github.com/Masterminds/sprig), so those functions can be used
+The tool also includes the [sprig templating library](https://github.com/Masterminds/sprig), so those functions can be used
 in the templates you supply.
 
-
 ### values.yaml metadata
 This tool can parse descriptions and defaults of values from `values.yaml` files. The defaults are pulled directly from
 the yaml in the file. 

cmd/helm-docs/command_line.go

@@ -43,15 +43,13 @@ func newHelmDocsCommand(run func(cmd *cobra.Command, args []string)) (*cobra.Com
 	}
 
 	logLevelUsage := fmt.Sprintf("Level of logs that should printed, one of (%s)", strings.Join(possibleLogLevels(), ", "))
+	command.PersistentFlags().StringP("chart-search-root", "c", ".", "directory to search recursively within for charts")
 	command.PersistentFlags().BoolP("dry-run", "d", false, "don't actually render any markdown files just print to stdout passed")
 	command.PersistentFlags().StringP("ignore-file", "i", ".helmdocsignore", "The filename to use as an ignore file to exclude chart directories")
 	command.PersistentFlags().StringP("log-level", "l", "info", logLevelUsage)
 	command.PersistentFlags().StringP("output-file", "o", "README.md", "markdown file path relative to each chart directory to which rendered documentation will be written")
-	command.PersistentFlags().StringP("template-file", "t", "README.md.gotmpl", "gotemplate file path relative to each chart directory from which documentation will be generated")
-	command.PersistentFlags().StringSliceP("template-files", "T", []string{"README.md.gotmpl"}, "gotemplate file paths relative to each chart directory from which documentation will be generated")
-	if err := command.PersistentFlags().MarkDeprecated("template-file", "in favor of template-files"); err != nil {
-		return command, err
-	}
+	command.PersistentFlags().StringSliceP("template-files", "t", []string{"README.md.gotmpl"}, "gotemplate file paths relative to each chart directory from which documentation will be generated")
+
 	viper.AutomaticEnv()
 	viper.SetEnvPrefix("HELM_DOCS")
 	viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_"))

cmd/helm-docs/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"os"
+	"path"
 	"strings"
 	"sync"
 
@@ -13,34 +14,48 @@ import (
 	"github.com/norwoodj/helm-docs/pkg/helm"
 )
 
-func retrieveInfoAndPrintDocumentation(chartDirectory string, waitGroup *sync.WaitGroup, dryRun bool) {
+func retrieveInfoAndPrintDocumentation(chartDirectory string, chartSearchRoot string, templateFiles []string, waitGroup *sync.WaitGroup, dryRun bool) {
 	defer waitGroup.Done()
-	chartDocumentationInfo, err := helm.ParseChartInformation(chartDirectory)
+	chartDocumentationInfo, err := helm.ParseChartInformation(path.Join(chartSearchRoot, chartDirectory))
 
 	if err != nil {
 		log.Warnf("Error parsing information for chart %s, skipping: %s", chartDirectory, err)
 		return
 	}
 
-	document.PrintDocumentation(chartDocumentationInfo, dryRun)
+	document.PrintDocumentation(chartDocumentationInfo, chartSearchRoot, templateFiles, dryRun)
 
 }
 
 func helmDocs(cmd *cobra.Command, _ []string) {
 	initializeCli()
-	chartDirs, err := helm.FindChartDirectories()
+
+	chartSearchRoot := viper.GetString("chart-search-root")
+	var fullChartSearchRoot string
+
+	if path.IsAbs(chartSearchRoot) {
+		fullChartSearchRoot = chartSearchRoot
+	} else {
+		cwd, err := os.Getwd()
+		if err != nil {
+			log.Warnf("Error getting working directory: %s", err)
+			return
+		}
+
+		fullChartSearchRoot = path.Join(cwd, chartSearchRoot)
+	}
+
+	chartDirs, err := helm.FindChartDirectories(fullChartSearchRoot)
 	if err != nil {
 		log.Errorf("Error finding chart directories: %s", err)
 		os.Exit(1)
 	}
-	if cmd.PersistentFlags().Changed("template-file") && cmd.PersistentFlags().Changed("template-files") {
-		log.Errorf("you cannot use both template-file and template-files. consider using just template-files")
-	} else if cmd.PersistentFlags().Changed("template-files") {
-		viper.Set("template-type", "template-files")
-	} else {
-		viper.Set("template-type", "template-file")
-	}
+
 	log.Infof("Found Chart directories [%s]", strings.Join(chartDirs, ", "))
+
+	templateFiles := viper.GetStringSlice("template-files")
+	log.Debugf("Rendering from optional template files [%s]", strings.Join(templateFiles, ", "))
+
 	dryRun := viper.GetBool("dry-run")
 	waitGroup := sync.WaitGroup{}
 
@@ -49,9 +64,9 @@ func helmDocs(cmd *cobra.Command, _ []string) {
 
 		// On dry runs all output goes to stdout, and so as to not jumble things, generate serially
 		if dryRun {
-			retrieveInfoAndPrintDocumentation(c, &waitGroup, dryRun)
+			retrieveInfoAndPrintDocumentation(c, fullChartSearchRoot, templateFiles, &waitGroup, dryRun)
 		} else {
-			go retrieveInfoAndPrintDocumentation(c, &waitGroup, dryRun)
+			go retrieveInfoAndPrintDocumentation(c, fullChartSearchRoot, templateFiles, &waitGroup, dryRun)
 		}
 	}
 

example-charts/_templates.gotmpl

@@ -0,0 +1,15 @@
+{{ define "extra.flower" -}}
+```
+          ,-.
+ ,     ,-.   ,-.
+/ \   (   )-(   )
+\ |  ,.>-(   )-<
+ \|,' (   )-(   )
+  Y ___`-'   `-'
+  |/__/   `-'
+  |
+  |
+  |    -hi-
+__|_____________
+```
+{{- end }}

example-charts/custom-template/README.md

@@ -6,6 +6,20 @@ Basically the same as the nginx-ingress chart, but using a custom template to in
 
 ## Additional Information
 
+```
+          ,-.
+ ,     ,-.   ,-.
+/ \   (   )-(   )
+\ |  ,.>-(   )-<
+ \|,' (   )-(   )
+  Y ___`-'   `-'
+  |/__/   `-'
+  |
+  |
+  |    -hi-
+__|_____________
+```
+
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore
 et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
 aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse

example-charts/custom-template/README.md.gotmpl

@@ -5,6 +5,8 @@
 
 ## Additional Information
 
+{{ template "extra.flower" . }}
+
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore
 et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
 aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse

example-charts/full-template/README.md

@@ -1,7 +1,21 @@
 # full-template
 
-## `chart.deprecationWarning`
+## `extra.flower`
+```
+          ,-.
+ ,     ,-.   ,-.
+/ \   (   )-(   )
+\ |  ,.>-(   )-<
+ \|,' (   )-(   )
+  Y ___`-'   `-'
+  |/__/   `-'
+  |
+  |
+  |    -hi-
+__|_____________
+```
 
+## `chart.deprecationWarning`
 > **:exclamation: This Helm Chart is deprecated!**
 
 ## `chart.name`

example-charts/full-template/README.md.gotmpl

@@ -1,13 +1,10 @@
 {{ template "chart.header" . }}
-## `chart.deprecationWarning`
-
-
-
-
-
 
 
+## `extra.flower`
+{{ template "extra.flower" . }}
 
+## `chart.deprecationWarning`
 {{ template "chart.deprecationWarning" . }}
 
 ## `chart.name`

example-charts/most-empty/README.md

@@ -5,3 +5,18 @@
 This is a good example of all the fields that don't appear when they aren't set in chart metadata. `description`,
 `requirements`, and `values` are all empty and don't appear here.
 
+There is a flower though:
+```
+          ,-.
+ ,     ,-.   ,-.
+/ \   (   )-(   )
+\ |  ,.>-(   )-<
+ \|,' (   )-(   )
+  Y ___`-'   `-'
+  |/__/   `-'
+  |
+  |
+  |    -hi-
+__|_____________
+```
+

example-charts/most-empty/README.md.gotmpl

@@ -6,6 +6,9 @@
 This is a good example of all the fields that don't appear when they aren't set in chart metadata. `description`,
 `requirements`, and `values` are all empty and don't appear here.
 
+There is a flower though:
+{{ template "extra.flower" . }}
+
 {{ template "chart.requirementsSection" . }}
 
 {{ template "chart.valuesSection" . }}

pkg/document/generate.go

@@ -2,8 +2,8 @@ package document
 
 import (
 	"bytes"
-	"fmt"
 	"os"
+	"path"
 	"path/filepath"
 	"regexp"
 
@@ -18,7 +18,7 @@ func getOutputFile(chartDirectory string, dryRun bool) (*os.File, error) {
 	}
 
 	outputFile := viper.GetString("output-file")
-	f, err := os.Create(fmt.Sprintf("%s/%s", chartDirectory, outputFile))
+	f, err := os.Create(path.Join(chartDirectory, outputFile))
 
 	if err != nil {
 		return nil, err
@@ -27,10 +27,15 @@ func getOutputFile(chartDirectory string, dryRun bool) (*os.File, error) {
 	return f, err
 }
 
-func PrintDocumentation(chartDocumentationInfo helm.ChartDocumentationInfo, dryRun bool) {
+func PrintDocumentation(chartDocumentationInfo helm.ChartDocumentationInfo, chartSearchRoot string, templateFiles []string, dryRun bool) {
 	log.Infof("Generating README Documentation for chart %s", chartDocumentationInfo.ChartDirectory)
 
-	chartDocumentationTemplate, err := newChartDocumentationTemplate(chartDocumentationInfo)
+	chartDocumentationTemplate, err := newChartDocumentationTemplate(
+		chartDocumentationInfo,
+		chartSearchRoot,
+		templateFiles,
+	)
+
 	if err != nil {
 		log.Warnf("Error generating gotemplates for chart %s: %s", chartDocumentationInfo.ChartDirectory, err)
 		return
@@ -57,6 +62,7 @@ func PrintDocumentation(chartDocumentationInfo helm.ChartDocumentationInfo, dryR
 	if err != nil {
 		log.Warnf("Error generating documentation for chart %s: %s", chartDocumentationInfo.ChartDirectory, err)
 	}
+
 	output = applyMarkDownFormat(output)
 	_, err = output.WriteTo(outputFile)
 	if err != nil {