Merge pull request #181 from edmondop/issue-169

Issue 169: Introduce strict linting options of values and exclusions

.github/workflows/build.yml

@@ -15,20 +15,22 @@ jobs:
     env:
       DOCKER_CLI_EXPERIMENTAL: "enabled"
     steps:
-    - uses: actions/checkout@v2
+    - name: Set up QEMU
+      uses: docker/setup-qemu-action@v2
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 0
-    - uses: docker/setup-qemu-action@v1
-    - uses: docker/setup-buildx-action@v1
-    - uses: actions/setup-go@v2
+    - uses: actions/setup-go@v4
       with:
         go-version: '^1.18.0'
-    - uses: actions/cache@v1
-      with:
-        path: /home/runner/go/pkg/mod
-        key: go-mod
-    - uses: goreleaser/goreleaser-action@v2
+    - name: Run GoReleaser
+      uses: goreleaser/goreleaser-action@v4
       with:
         args: release --snapshot --skip-sign
+      env:
+        PROJECT_ROOT: ${{ github.workspace }}
     - if: always()
       run: rm -f ${HOME}/.docker/config.json
+

.github/workflows/release.yml

@@ -11,30 +11,29 @@ jobs:
     env:
       DOCKER_CLI_EXPERIMENTAL: "enabled"
     steps:
-    - uses: actions/checkout@v2
+    - name: Set up QEMU
+      uses: docker/setup-qemu-action@v2
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 0
-    - uses: docker/setup-qemu-action@v1
-    - uses: docker/setup-buildx-action@v1
-    - uses: actions/setup-go@v2
+    - uses: actions/setup-go@v4
       with:
         go-version: '^1.18.0'
-    - uses: actions/cache@v1
-      with:
-        path: /home/runner/go/pkg/mod
-        key: go-mod
     - name: Login to Docker hub
       run: docker login -u ${{ secrets.DOCKER_HUB_USER }} -p ${{ secrets.DOCKER_HUB_PASSWORD }}
     - name: Import GPG key
       id: import_gpg
       uses: crazy-max/ghaction-import-gpg@v4
       with:
         gpg_private_key: ${{ secrets.SIGNING_KEY }}
-    - uses: goreleaser/goreleaser-action@v2
+    - uses: goreleaser/goreleaser-action@v4
       with:
         args: release
       env:
         GITHUB_TOKEN: ${{ secrets.NORWOODJ_ORG_TOKEN }}
         GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }}
+        PROJECT_ROOT: ${{ env.GITHUB_WORKSPACE }}
     - if: always()
       run: rm -f ${HOME}/.docker/config.json

.goreleaser.yml

@@ -1,3 +1,6 @@
+project_name: helm-docs
+env:
+  - PROJECT_ROOT={{ .Env.PROJECT_ROOT }}
 before:
   hooks:
     - go mod download
@@ -18,12 +21,15 @@ builds:
       - linux
       - windows
 archives:
-  - replacements:
-      darwin: Darwin
-      linux: Linux
-      windows: Windows
-      386: i386
-      amd64: x86_64
+  - id: default
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- title .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else if eq .Arch "arm" }}{{ .Arch }}{{ .Arm }}
+      {{- else }}{{ .Arch }}{{ end }}
+
 checksum:
   name_template: checksums.txt
 snapshot:
@@ -48,12 +54,16 @@ nfpms:
   formats:
   - deb
   - rpm
-  replacements:
-    amd64: x86_64
-    linux: Linux
+  file_name_template: >-
+    {{ .ProjectName }}_
+    {{- title .Os }}_
+    {{- if eq .Arch "amd64" }}x86_64
+    {{- else if eq .Arch "386" }}i386
+    {{- else if eq .Arch "arm" }}{{ .Arch }}{{ .Arm }}
+    {{- else }}{{ .Arch }}{{ end }}
 
 brews:
-  - tap:
+  - repository:
       owner: norwoodj
       name: homebrew
     folder: Formula

README.md

@@ -431,3 +431,76 @@ markdown or markdownX files to be processed by Gatsby or Hugo into
 a static Web/Javascript page.
 
 For a more concrete examples on how to do these custom rendering, see [example here](./example-charts/custom-value-notation-type/README.md)
+
+
+## Strict linting
+
+Sometimes you might want to enforce helm-docs to fail when some values are not documented correctly.
+
+By default, this option is turned off:
+
+```shell
+./helm-docs -c  example-charts/helm-3
+INFO[2023-06-29T07:54:29-07:00] Found Chart directories [.]                  
+INFO[2023-06-29T07:54:29-07:00] Generating README Documentation for chart example-charts/helm-3 
+```
+
+but you can use the `-x` flag to turn it on:
+
+```shell
+helm-docs -x -c  example-charts/helm-3
+INFO[2023-06-29T07:55:12-07:00] Found Chart directories [.]                  
+WARN[2023-06-29T07:55:12-07:00] Error parsing information for chart ., skipping: values without documentation: 
+controller
+controller.name
+controller.image
+controller.extraVolumes.[0].name
+controller.extraVolumes.[0].configMap
+controller.extraVolumes.[0].configMap.name
+controller.livenessProbe.httpGet
+controller.livenessProbe.httpGet.port
+controller.publishService
+controller.service
+controller.service.annotations
+controller.service.annotations.external-dns.alpha.kubernetes.io/hostname
+```
+
+The CLI also supports excluding fields by regexp using the `-z` argument
+
+```shell
+helm-docs -x -z="controller.*" -c  example-charts/helm-3
+INFO[2023-06-29T08:18:55-07:00] Found Chart directories [.]                  
+INFO[2023-06-29T08:18:55-07:00] Generating README Documentation for chart example-charts/helm-3 
+```
+
+Multiple regexp can be passed, as in the following example:  
+
+```shell
+helm-docs -x -z="controller.image.*" -z="controller.service.*"  -z="controller.extraVolumes.*"  -c  example-charts/helm-3
+INFO[2023-06-29T08:21:04-07:00] Found Chart directories [.]                  
+WARN[2023-06-29T08:21:04-07:00] Error parsing information for chart ., skipping: values without documentation: 
+controller
+controller.name
+controller.livenessProbe.httpGet
+controller.livenessProbe.httpGet.port
+controller.publishService 
+```
+
+It is also possible to ignore specific errors using the `-y` argument.
+
+```shell
+helm-docs -x -y="controller.name" -y="controller.service"  -c  example-charts/helm-3
+INFO[2023-06-29T08:23:40-07:00] Found Chart directories [.]                  
+WARN[2023-06-29T08:23:40-07:00] Error parsing information for chart ., skipping: values without documentation: 
+controller
+controller.image
+controller.extraVolumes.[0].name
+controller.extraVolumes.[0].configMap
+controller.extraVolumes.[0].configMap.name
+controller.livenessProbe.httpGet
+controller.livenessProbe.httpGet.port
+controller.publishService
+controller.service.annotations
+controller.service.annotations.external-dns.alpha.kubernetes.io/hostname 
+
+```

cmd/helm-docs/command_line.go

@@ -56,6 +56,9 @@ func newHelmDocsCommand(run func(cmd *cobra.Command, args []string)) (*cobra.Com
 	command.PersistentFlags().StringP("values-file", "f", "values.yaml", "Path to values file")
 	command.PersistentFlags().BoolP("document-dependency-values", "u", false, "For charts with dependencies, include the dependency values in the chart values documentation")
 	command.PersistentFlags().StringSliceP("chart-to-generate", "g", []string{}, "List of charts that will have documentation generated. Comma separated, no space. Empty list - generate for all charts in chart-search-root")
+	command.PersistentFlags().BoolP("documentation-strict-mode", "x", false, "Fail the generation of docs if there are undocumented values")
+	command.PersistentFlags().StringSliceP("documentation-strict-ignore-absent", "y", []string{"service.type", "image.repository", "image.tag"}, "A comma separate values which are allowed not to be documented in strict mode")
+	command.PersistentFlags().StringSliceP("documentation-strict-ignore-absent-regex", "z", []string{".*service\\.type", ".*image\\.repository", ".*image\\.tag"}, "A comma separate values which are allowed not to be documented in strict mode")
 
 	viper.AutomaticEnv()
 	viper.SetEnvPrefix("HELM_DOCS")

cmd/helm-docs/main.go

@@ -6,6 +6,7 @@ import (
 	"path"
 	"path/filepath"
 	"reflect"
+	"regexp"
 	"runtime"
 	"strings"
 	"sync"
@@ -53,6 +54,23 @@ func parallelProcessIterable(iterable interface{}, parallelism int, visitFn func
 	wg.Wait()
 }
 
+func getDocumentationParsingConfigFromArgs() (helm.ChartValuesDocumentationParsingConfig, error) {
+	var regexps []*regexp.Regexp
+	regexpStrings := viper.GetStringSlice("documentation-strict-ignore-absent-regex")
+	for _, item := range regexpStrings {
+		regex, err := regexp.Compile(item)
+		if err != nil {
+			return helm.ChartValuesDocumentationParsingConfig{}, err
+		}
+		regexps = append(regexps, regex)
+	}
+	return helm.ChartValuesDocumentationParsingConfig{
+		StrictMode:                 viper.GetBool("documentation-strict-mode"),
+		AllowedMissingValuePaths:   viper.GetStringSlice("documentation-strict-ignore-absent"),
+		AllowedMissingValueRegexps: regexps,
+	}, nil
+}
+
 func readDocumentationInfoByChartPath(chartSearchRoot string, parallelism int) (map[string]helm.ChartDocumentationInfo, error) {
 	var fullChartSearchRoot string
 
@@ -79,10 +97,14 @@ func readDocumentationInfoByChartPath(chartSearchRoot string, parallelism int) (
 
 	documentationInfoByChartPath := make(map[string]helm.ChartDocumentationInfo, len(chartDirs))
 	documentationInfoByChartPathMu := &sync.Mutex{}
+	documentationParsingConfig, err := getDocumentationParsingConfigFromArgs()
+	if err != nil {
+		return nil, fmt.Errorf("error parsing the linting config%w", err)
+	}
 
 	parallelProcessIterable(chartDirs, parallelism, func(elem interface{}) {
 		chartDir := elem.(string)
-		info, err := helm.ParseChartInformation(filepath.Join(chartSearchRoot, chartDir))
+		info, err := helm.ParseChartInformation(filepath.Join(chartSearchRoot, chartDir), documentationParsingConfig)
 		if err != nil {
 			log.Warnf("Error parsing information for chart %s, skipping: %s", chartDir, err)
 			return

example-charts/fully-documented/Chart.yaml

@@ -0,0 +1,15 @@
+apiVersion: v2
+name: nginx-ingress
+description: A simple wrapper around the stable/nginx-ingress chart that adds a few of our conventions
+version: "0.2.0"
+home: "https://github.com/norwoodj/helm-docs/tree/master/example-charts/nginx-ingress"
+sources: ["https://github.com/norwoodj/helm-docs/tree/master/example-charts/nginx-ingress"]
+engine: gotpl
+type: application
+maintainers:
+  - email: norwood.john.m@gmail.com
+    name: John Norwood
+dependencies:
+  - name: nginx-ingress
+    version: "0.22.1"
+    repository: "@stable"

example-charts/fully-documented/README.md

@@ -0,0 +1,34 @@
+# nginx-ingress
+
+![Version: 0.2.0](https://img.shields.io/badge/Version-0.2.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)
+
+A simple wrapper around the stable/nginx-ingress chart that adds a few of our conventions
+
+**Homepage:** <https://github.com/norwoodj/helm-docs/tree/master/example-charts/nginx-ingress>
+
+## Maintainers
+
+| Name | Email | Url |
+| ---- | ------ | --- |
+| John Norwood | <norwood.john.m@gmail.com> |  |
+
+## Source Code
+
+* <https://github.com/norwoodj/helm-docs/tree/master/example-charts/nginx-ingress>
+
+## Requirements
+
+| Repository | Name | Version |
+|------------|------|---------|
+| @stable | nginx-ingress | 0.22.1 |
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| controller | object | `{"image":{"repository":"nginx-ingress-controller","tag":"18.0831"},"name":"controller"}` | The controller |
+| controller.image | object | `{"repository":"nginx-ingress-controller","tag":"18.0831"}` | The image of the controller |
+| controller.image.repository | string | `"nginx-ingress-controller"` | The repository of the controller |
+| controller.image.tag | string | `"18.0831"` | The tag of the image of the controller |
+| controller.name | string | `"controller"` | The name of the controller |
+

example-charts/fully-documented/values.yaml

@@ -0,0 +1,10 @@
+# controller -- The controller
+controller:
+  # controller.name -- The name of the controller
+  name: controller
+  # controller.image -- The image of the controller
+  image:
+    # controller.image.repository -- The repository of the controller
+    repository: nginx-ingress-controller
+    # controller.image.tag -- The tag of the image of the controller
+    tag: "18.0831"