Skip to content

Commit 02f4425

Browse files
norwoodjnorwoodj
committed
feat: updates to add chart search path flag and to search for template files differently based on how they're presented fixes #47 
1 parent a43ccae commit 02f4425

File tree

15 files changed

+173
-64
lines changed

15 files changed

+173
-64
lines changed

‎.pre-commit-config.yaml

+5
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,8 @@ repos:
33
rev: v0.8.0
44
hooks:
55
- id: helm-docs
6+
args:
7+
- --chart-search-root=example-charts
8+
- --template-files=./_templates.gotmpl
9+
- --template-files=README.gotmpl
10+
- --log-level=debug

‎README.md

+19-15
Original file line numberDiff line numberDiff line change
@@ -107,17 +107,26 @@ when searching for charts. Directories specified need not be charts themselves,
107107
many charts can be ignored and none of the charts underneath them will be processed. You may also directly reference the
108108
Chart.yaml file for a chart to skip processing for it.
109109

110-
111110
## Markdown Rendering
112-
The helm-docs tool uses go-templates to render output documentation. There are a number of sub-templates that are
113-
referenced in the internal default template and can be used by custom `README.md.gotmpl` templates your repository provides as well.
111+
There are two important paramaters to be aware of when running helm-docs. `--chart-serach-root` specifies the directory
112+
under which the tool will recursively search for charts to render documentation for. `--template-files` specifies the list
113+
of gotemplate files that should be used in rendering the resulting markdown file for each chart found. By default
114+
`--chart-search-root=.` and `--template-files=README.md.gotmpl`.
114115

115-
Templates can be invoked like so:
116-
```
117-
{{ template "template-name" . }}
118-
```
116+
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_.
117+
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`
118+
then the file is interpreted as being relative to the `chart-search-root`.
119+
120+
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)
121+
here, you'll see our search root is set to [example-charts](./example-charts) and the list of templates used for each chart
122+
is the [_templates.gotmpl file in that directory](./example-charts/_templates.gotmpl) and the README.md.gotmpl file in
123+
each chart directory.
119124

120-
And the complete listing of available templates is below:
125+
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)
126+
file, then the internal default template is used instead.
127+
128+
In addition to extra defined templates you specify in these template files, there are quite a few built-in templates that
129+
can be used as well:
121130

122131
| Name | Description |
123132
|------|-------------|
@@ -148,11 +157,7 @@ And the complete listing of available templates is below:
148157
| chart.valuesTable | A table of the chart's values parsed from the `values.yaml` file (see below) |
149158
| chart.valuesSection | A section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no values |
150159

151-
For an example of how these various templates can be used in a `README.md.gotmpl` file to generate a reasonable markdown file,
152-
look at the charts in [example-charts](./example-charts).
153-
154-
If there is no `README.md.gotmpl` (or other specified gotmpl file) present, the default template is used to generate the README.
155-
That template looks like so:
160+
The default internal template mentioned above uses many of these and looks like this:
156161
```
157162
{{ template "chart.header" . }}
158163
{{ template "chart.deprecationWarning" . }}
@@ -172,10 +177,9 @@ That template looks like so:
172177
{{ template "chart.valuesSection" . }}
173178
```
174179

175-
The tool includes the [sprig templating library](https://github.com/Masterminds/sprig), so those functions can be used
180+
The tool also includes the [sprig templating library](https://github.com/Masterminds/sprig), so those functions can be used
176181
in the templates you supply.
177182

178-
179183
### values.yaml metadata
180184
This tool can parse descriptions and defaults of values from `values.yaml` files. The defaults are pulled directly from
181185
the yaml in the file.

‎cmd/helm-docs/command_line.go

+3-5
Original file line numberDiff line numberDiff line change
@@ -43,15 +43,13 @@ func newHelmDocsCommand(run func(cmd *cobra.Command, args []string)) (*cobra.Com
4343
}
4444

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

‎cmd/helm-docs/main.go

+28-13
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ package main
22

33
import (
44
"os"
5+
"path"
56
"strings"
67
"sync"
78

@@ -13,34 +14,48 @@ import (
1314
"github.com/norwoodj/helm-docs/pkg/helm"
1415
)
1516

16-
func retrieveInfoAndPrintDocumentation(chartDirectory string, waitGroup *sync.WaitGroup, dryRun bool) {
17+
func retrieveInfoAndPrintDocumentation(chartDirectory string, chartSearchRoot string, templateFiles []string, waitGroup *sync.WaitGroup, dryRun bool) {
1718
defer waitGroup.Done()
18-
chartDocumentationInfo, err := helm.ParseChartInformation(chartDirectory)
19+
chartDocumentationInfo, err := helm.ParseChartInformation(path.Join(chartSearchRoot, chartDirectory))
1920

2021
if err != nil {
2122
log.Warnf("Error parsing information for chart %s, skipping: %s", chartDirectory, err)
2223
return
2324
}
2425

25-
document.PrintDocumentation(chartDocumentationInfo, dryRun)
26+
document.PrintDocumentation(chartDocumentationInfo, chartSearchRoot, templateFiles, dryRun)
2627

2728
}
2829

2930
func helmDocs(cmd *cobra.Command, _ []string) {
3031
initializeCli()
31-
chartDirs, err := helm.FindChartDirectories()
32+
33+
chartSearchRoot := viper.GetString("chart-search-root")
34+
var fullChartSearchRoot string
35+
36+
if path.IsAbs(chartSearchRoot) {
37+
fullChartSearchRoot = chartSearchRoot
38+
} else {
39+
cwd, err := os.Getwd()
40+
if err != nil {
41+
log.Warnf("Error getting working directory: %s", err)
42+
return
43+
}
44+
45+
fullChartSearchRoot = path.Join(cwd, chartSearchRoot)
46+
}
47+
48+
chartDirs, err := helm.FindChartDirectories(fullChartSearchRoot)
3249
if err != nil {
3350
log.Errorf("Error finding chart directories: %s", err)
3451
os.Exit(1)
3552
}
36-
if cmd.PersistentFlags().Changed("template-file") && cmd.PersistentFlags().Changed("template-files") {
37-
log.Errorf("you cannot use both template-file and template-files. consider using just template-files")
38-
} else if cmd.PersistentFlags().Changed("template-files") {
39-
viper.Set("template-type", "template-files")
40-
} else {
41-
viper.Set("template-type", "template-file")
42-
}
53+
4354
log.Infof("Found Chart directories [%s]", strings.Join(chartDirs, ", "))
55+
56+
templateFiles := viper.GetStringSlice("template-files")
57+
log.Debugf("Rendering from optional template files [%s]", strings.Join(templateFiles, ", "))
58+
4459
dryRun := viper.GetBool("dry-run")
4560
waitGroup := sync.WaitGroup{}
4661

@@ -49,9 +64,9 @@ func helmDocs(cmd *cobra.Command, _ []string) {
4964

5065
// On dry runs all output goes to stdout, and so as to not jumble things, generate serially
5166
if dryRun {
52-
retrieveInfoAndPrintDocumentation(c, &waitGroup, dryRun)
67+
retrieveInfoAndPrintDocumentation(c, fullChartSearchRoot, templateFiles, &waitGroup, dryRun)
5368
} else {
54-
go retrieveInfoAndPrintDocumentation(c, &waitGroup, dryRun)
69+
go retrieveInfoAndPrintDocumentation(c, fullChartSearchRoot, templateFiles, &waitGroup, dryRun)
5570
}
5671
}
5772

‎example-charts/_templates.gotmpl

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{{ define "extra.flower" -}}
2+
```
3+
,-.
4+
, ,-. ,-.
5+
/ \ ( )-( )
6+
\ | ,.>-( )-<
7+
\|,' ( )-( )
8+
Y ___`-' `-'
9+
|/__/ `-'
10+
|
11+
|
12+
| -hi-
13+
__|_____________
14+
```
15+
{{- end }}

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

+14
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,20 @@ Basically the same as the nginx-ingress chart, but using a custom template to in
66

77
## Additional Information
88

9+
```
10+
,-.
11+
, ,-. ,-.
12+
/ \ ( )-( )
13+
\ | ,.>-( )-<
14+
\|,' ( )-( )
15+
Y ___`-' `-'
16+
|/__/ `-'
17+
|
18+
|
19+
| -hi-
20+
__|_____________
21+
```
22+
923
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore
1024
et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
1125
aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse

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

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55

66
## Additional Information
77

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

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

+15-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,21 @@
11
# full-template
22

3-
## `chart.deprecationWarning`
3+
## `extra.flower`
4+
```
5+
,-.
6+
, ,-. ,-.
7+
/ \ ( )-( )
8+
\ | ,.>-( )-<
9+
\|,' ( )-( )
10+
Y ___`-' `-'
11+
|/__/ `-'
12+
|
13+
|
14+
| -hi-
15+
__|_____________
16+
```
417

18+
## `chart.deprecationWarning`
519
> **:exclamation: This Helm Chart is deprecated!**
620
721
## `chart.name`

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

+3-6
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
11
{{ template "chart.header" . }}
2-
## `chart.deprecationWarning`
3-
4-
5-
6-
7-
82

93

4+
## `extra.flower`
5+
{{ template "extra.flower" . }}
106

7+
## `chart.deprecationWarning`
118
{{ template "chart.deprecationWarning" . }}
129

1310
## `chart.name`

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

+15
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,18 @@
55
This is a good example of all the fields that don't appear when they aren't set in chart metadata. `description`,
66
`requirements`, and `values` are all empty and don't appear here.
77

8+
There is a flower though:
9+
```
10+
,-.
11+
, ,-. ,-.
12+
/ \ ( )-( )
13+
\ | ,.>-( )-<
14+
\|,' ( )-( )
15+
Y ___`-' `-'
16+
|/__/ `-'
17+
|
18+
|
19+
| -hi-
20+
__|_____________
21+
```
22+

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

+3
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66
This is a good example of all the fields that don't appear when they aren't set in chart metadata. `description`,
77
`requirements`, and `values` are all empty and don't appear here.
88

9+
There is a flower though:
10+
{{ template "extra.flower" . }}
11+
912
{{ template "chart.requirementsSection" . }}
1013

1114
{{ template "chart.valuesSection" . }}

‎pkg/document/generate.go

+10-4
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ package document
22

33
import (
44
"bytes"
5-
"fmt"
65
"os"
6+
"path"
77
"path/filepath"
88
"regexp"
99

@@ -18,7 +18,7 @@ func getOutputFile(chartDirectory string, dryRun bool) (*os.File, error) {
1818
}
1919

2020
outputFile := viper.GetString("output-file")
21-
f, err := os.Create(fmt.Sprintf("%s/%s", chartDirectory, outputFile))
21+
f, err := os.Create(path.Join(chartDirectory, outputFile))
2222

2323
if err != nil {
2424
return nil, err
@@ -27,10 +27,15 @@ func getOutputFile(chartDirectory string, dryRun bool) (*os.File, error) {
2727
return f, err
2828
}
2929

30-
func PrintDocumentation(chartDocumentationInfo helm.ChartDocumentationInfo, dryRun bool) {
30+
func PrintDocumentation(chartDocumentationInfo helm.ChartDocumentationInfo, chartSearchRoot string, templateFiles []string, dryRun bool) {
3131
log.Infof("Generating README Documentation for chart %s", chartDocumentationInfo.ChartDirectory)
3232

33-
chartDocumentationTemplate, err := newChartDocumentationTemplate(chartDocumentationInfo)
33+
chartDocumentationTemplate, err := newChartDocumentationTemplate(
34+
chartDocumentationInfo,
35+
chartSearchRoot,
36+
templateFiles,
37+
)
38+
3439
if err != nil {
3540
log.Warnf("Error generating gotemplates for chart %s: %s", chartDocumentationInfo.ChartDirectory, err)
3641
return
@@ -57,6 +62,7 @@ func PrintDocumentation(chartDocumentationInfo helm.ChartDocumentationInfo, dryR
5762
if err != nil {
5863
log.Warnf("Error generating documentation for chart %s: %s", chartDocumentationInfo.ChartDirectory, err)
5964
}
65+
6066
output = applyMarkDownFormat(output)
6167
_, err = output.WriteTo(outputFile)
6268
if err != nil {

0 commit comments

Comments
 (0)