Merge pull request norwoodj#64 from norwoodj/jnorwood/comprehensive-e…

…xample

feat: adds a new chart with good examples, cleans up README a bit mor…

.pre-commit-config.yaml

@@ -4,7 +4,12 @@ repos:
     hooks:
       - id: helm-docs
         args:
+          # Make the tool search for charts only under the `example-charts` directory
           - --chart-search-root=example-charts
+
+          # The `./` makes it relative to the chart-search-root set above
           - --template-files=./_templates.gotmpl
+
+          # Repeating the flag adds this to the list, now [./_templates.gotmpl, README.md.gotmpl]
+          # A base filename makes it relative to each chart directory found
           - --template-files=README.md.gotmpl
-          - --log-level=debug

README.md

@@ -2,31 +2,58 @@ helm-docs
 =========
 [![Go Report Card](https://goreportcard.com/badge/github.com/norwoodj/helm-docs)](https://goreportcard.com/report/github.com/norwoodj/helm-docs)
 
-The helm-docs tool generates automatic documentation from helm charts into a markdown file. The resulting
-file contains metadata about the chart and a table with all of your charts' values, their defaults, and an
+The helm-docs tool auto-generates documentation from helm charts into markdown files. The resulting
+files contain metadata about their respective chart and a table with each of the chart's values, their defaults, and an
 optional description parsed from comments.
 
 The markdown generation is entirely [gotemplate](https://golang.org/pkg/text/template) driven. The tool parses metadata
 from charts and generates a number of sub-templates that can be referenced in a template file (by default `README.md.gotmpl`).
 If no template file is provided, the tool has a default internal template that will generate a reasonably formatted README.
 
-In particular, this tool will auto-detect descriptions of fields from comments:
+The most useful aspect of this tool is the auto-detection of field descriptions from comments:
 ```yaml
-controller:
-  # -- Configure the healthcheck for the ingress controller
-  livenessProbe:
-    httpGet:
-      # -- This is the liveness check endpoint
-      path: /healthz
+config:
+  databasesToCreate:
+    # -- default database for storage of database metadata
+    - postgres
+
+    # -- database for the [hashbash](https://github.com/norwoodj/hashbash) project
+    - hashbash
+
+  usersToCreate:
+    # -- admin user
+    - {name: root, admin: true}
+
+    # -- user with access to the database with the same name
+    - {name: hashbash, readwriteDatabases: [hashbash]}
+
+statefulset:
+  image:
+    # -- Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files
+    repository: jnorwood/postgresql
+    tag: "11"
+
+  # -- Additional volumes to be mounted into the database container
+  extraVolumes:
+    - name: data
+      emptyDir: {}
 ```
 
 Resulting in a resulting README section like so:
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| controller.livenessProbe | object | `{"httpGet":{"path":"/healthz","port":8080}}` | Configure the healthcheck for the ingress controller |
-| controller.livenessProbe.httpGet.path | string | `"/healthz"` | This is the liveness check endpoint |
-
+| config.databasesToCreate[0] | string | `"postgresql"` | default database for storage of database metadata |
+| config.databasesToCreate[1] | string | `"hashbash"` | database for the [hashbash](https://github.com/norwoodj/hashbash) project |
+| config.usersToCreate[0] | object | `{"admin":true,"name":"root"}` | admin user |
+| config.usersToCreate[1] | object | `{"name":"hashbash","readwriteDatabases":["hashbash"]}` | user with access to the database with the same name |
+| statefulset.extraVolumes | list | `[{"emptyDir":{},"name":"data"}]` | Additional volumes to be mounted into the database container |
+| statefulset.image.repository | string | `"jnorwood/postgresql:11"` | Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files |
+| statefulset.image.tag | string | `"18.0831"` |  |
+
+You'll notice that some complex fields (lists and objects) are documented while others aren't, and that some simple fields
+like `statefulset.image.tag` are documented even without a description comment. The rules for what is and isn't documented in
+the final table will be described in detail later in this document.
 
 ## Installation
 helm-docs can be installed using [homebrew](https://brew.sh/):
@@ -89,18 +116,6 @@ Then run:
 docker run --rm --volume "$(pwd):/helm-docs" -u $(id -u) jnorwood/helm-docs:latest
 ```
 
-### Building from source
-Notice that you need to have build chain toolkit for given platform and golang installed.
-Next you may need to export some vars to build standalone, non-linked binary for given platform and architecture:
-
-```bash
-export CGO_ENABLED=0 GOOS=linux GOARCH=amd64
-make clean
-make fmt
-make test
-make
-```
-
 ## Ignoring Chart Directories
 helm-docs supports a `.helmdocsignore` file, exactly like a `.gitignore` file in which one can specify directories to ignore
 when searching for charts. Directories specified need not be charts themselves, so parent directories containing potentially
@@ -249,7 +264,7 @@ Results in:
 | controller.livenessProbe.httpGet.path | string | `"/healthz"` | This is the liveness check endpoint |
 
 If we remove the comment for `controller.livenessProbe` however, both leaf nodes `controller.livenessProbe.httpGet.path`
-and `controller.livenessProbe.httpGet.port` will be added to the table, with our without description comments:
+and `controller.livenessProbe.httpGet.port` will be added to the table, with or without description comments:
 
 ```yaml
 controller:

example-charts/best-values-example/Chart.yaml

@@ -0,0 +1,11 @@
+apiVersion: v2
+name: best-values-example
+description: One of the best values parsing example charts here, exhibits several more complicated examples
+version: "0.2.0"
+home: "https://github.com/norwoodj/helm-docs/tree/master/example-charts/best-values-example"
+sources: ["https://github.com/norwoodj/helm-docs/tree/master/example-charts/best-values-example"]
+engine: gotpl
+type: application
+maintainers:
+  - email: [email protected]
+    name: John Norwood

example-charts/best-values-example/README.md

@@ -0,0 +1,34 @@
+# best-values-example
+
+![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)
+
+One of the best values parsing example charts here, exhibits several more complicated examples
+
+**Homepage:** <https://github.com/norwoodj/helm-docs/tree/master/example-charts/best-values-example>
+
+## Maintainers
+
+| Name | Email | Url |
+| ---- | ------ | --- |
+| John Norwood | [email protected] |  |
+
+## Source Code
+
+* <https://github.com/norwoodj/helm-docs/tree/master/example-charts/best-values-example>
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| config.databasesToCreate[0] | string | `"postgresql"` | default database for storage of database metadata |
+| config.databasesToCreate[1] | string | `"hashbash"` | database for the [hashbash](https://github.com/norwoodj/hashbash) project |
+| config.usersToCreate[0] | object | `{"admin":true,"name":"root"}` | admin user |
+| config.usersToCreate[1] | object | `{"name":"hashbash","readwriteDatabases":["hashbash"]}` | user with access to the database with the same name |
+| statefulset.extraVolumes | list | `[{"emptyDir":{},"name":"data"}]` | Additional volumes to be mounted into the database container |
+| statefulset.image.repository | string | `"jnorwood/postgresq"` | Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files |
+| statefulset.image.tag | string | `"11"` |  |
+| statefulset.livenessProbe | object | `{"enabled":false}` | Configure the healthcheck for the database |
+| statefulset.podLabels | object | `{}` | The labels to be applied to instances of the database |
+
+----------------------------------------------
+Autogenerated from chart metadata using [helm-docs v1.2.1](https://github.com/norwoodj/helm-docs/releases/v1.2.1)

example-charts/best-values-example/values.yaml

@@ -0,0 +1,32 @@
+statefulset:
+  image:
+    # -- Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files
+    repository: jnorwood/postgresq
+    tag: "11"
+
+  # -- Additional volumes to be mounted into the database container
+  extraVolumes:
+    - name: data
+      emptyDir: {}
+
+  # -- Configure the healthcheck for the database
+  livenessProbe:
+    enabled: false
+
+  # -- The labels to be applied to instances of the database
+  podLabels: {}
+
+config:
+  databasesToCreate:
+    # -- default database for storage of database metadata
+    - postgresql
+
+    # -- database for the [hashbash](https://github.com/norwoodj/hashbash) project
+    - hashbash
+
+  usersToCreate:
+    # -- admin user
+    - {name: root, admin: true}
+
+    # -- user with access to the database with the same name
+    - {name: hashbash, readwriteDatabases: [hashbash]}

pkg/document/model.go

@@ -20,15 +20,15 @@ type valueRow struct {
 type chartTemplateData struct {
 	helm.ChartDocumentationInfo
 	HelmDocsVersion string
-	Values []valueRow
+	Values          []valueRow
 }
 
 func getChartTemplateData(chartDocumentationInfo helm.ChartDocumentationInfo, helmDocsVersion string) (chartTemplateData, error) {
 	// handle empty values file case
 	if chartDocumentationInfo.ChartValues.Kind == 0 {
 		return chartTemplateData{
 			ChartDocumentationInfo: chartDocumentationInfo,
-			HelmDocsVersion: helmDocsVersion,
+			HelmDocsVersion:        helmDocsVersion,
 			Values:                 make([]valueRow, 0),
 		}, nil
 	}
@@ -54,7 +54,7 @@ func getChartTemplateData(chartDocumentationInfo helm.ChartDocumentationInfo, he
 
 	return chartTemplateData{
 		ChartDocumentationInfo: chartDocumentationInfo,
-		HelmDocsVersion: helmDocsVersion,
+		HelmDocsVersion:        helmDocsVersion,
 		Values:                 valuesTableRows,
 	}, nil
 }

pkg/document/values.go

@@ -225,7 +225,11 @@ func getDescriptionFromNode(node *yaml.Node) helm.ChartValueDescription {
 		return helm.ChartValueDescription{}
 	}
 
-	_, c := helm.ParseComment(match[1], commentLines)
+	keyFromComment, c := helm.ParseComment(commentLines)
+	if keyFromComment != "" {
+		return helm.ChartValueDescription{}
+	}
+
 	return c
 }
 

pkg/helm/chart_info.go

@@ -197,7 +197,7 @@ func parseChartValuesFileComments(chartDirectory string) (map[string]ChartValueD
 
 		// If we haven't continued by this point, we didn't match any of the comment formats we want, so we need to add
 		// the in progress value to the map, and reset to looking for a new key
-		key, description := ParseComment("", commentLines)
+		key, description := ParseComment(commentLines)
 		keyToDescriptions[key] = description
 		commentLines = make([]string, 0)
 		foundValuesComment = false

pkg/helm/comment.go

@@ -1,6 +1,7 @@
 package helm
 
-func ParseComment(valueKey string, commentLines []string) (string, ChartValueDescription) {
+func ParseComment(commentLines []string) (string, ChartValueDescription) {
+	var valueKey string
 	var c ChartValueDescription
 
 	match := valuesDescriptionRegex.FindStringSubmatch(commentLines[0])