From 4acbc687f798c40befeb5fa19bfb3d5677c20595 Mon Sep 17 00:00:00 2001 From: John Norwood Date: Tue, 6 Oct 2020 03:54:07 +0000 Subject: [PATCH] feat: adds a new chart with good examples, cleans up README a bit more, and shhhh... fixes a bug --- .pre-commit-config.yaml | 7 +- README.md | 65 ++++++++++++------- example-charts/best-values-example/Chart.yaml | 11 ++++ example-charts/best-values-example/README.md | 34 ++++++++++ .../best-values-example/values.yaml | 32 +++++++++ pkg/document/model.go | 6 +- pkg/document/values.go | 6 +- pkg/helm/chart_info.go | 2 +- pkg/helm/comment.go | 3 +- 9 files changed, 134 insertions(+), 32 deletions(-) create mode 100644 example-charts/best-values-example/Chart.yaml create mode 100644 example-charts/best-values-example/README.md create mode 100644 example-charts/best-values-example/values.yaml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dae67c0..1bc2cfb 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/README.md b/README.md index 2f9002e..d764ce5 100644 --- a/README.md +++ b/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: diff --git a/example-charts/best-values-example/Chart.yaml b/example-charts/best-values-example/Chart.yaml new file mode 100644 index 0000000..1848555 --- /dev/null +++ b/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: norwood.john.m@gmail.com + name: John Norwood diff --git a/example-charts/best-values-example/README.md b/example-charts/best-values-example/README.md new file mode 100644 index 0000000..3e075fa --- /dev/null +++ b/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:** + +## Maintainers + +| Name | Email | Url | +| ---- | ------ | --- | +| John Norwood | norwood.john.m@gmail.com | | + +## Source Code + +* + +## 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) diff --git a/example-charts/best-values-example/values.yaml b/example-charts/best-values-example/values.yaml new file mode 100644 index 0000000..a218d30 --- /dev/null +++ b/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]} diff --git a/pkg/document/model.go b/pkg/document/model.go index 89f17da..f14e0ea 100644 --- a/pkg/document/model.go +++ b/pkg/document/model.go @@ -20,7 +20,7 @@ type valueRow struct { type chartTemplateData struct { helm.ChartDocumentationInfo HelmDocsVersion string - Values []valueRow + Values []valueRow } func getChartTemplateData(chartDocumentationInfo helm.ChartDocumentationInfo, helmDocsVersion string) (chartTemplateData, error) { @@ -28,7 +28,7 @@ func getChartTemplateData(chartDocumentationInfo helm.ChartDocumentationInfo, he 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 } diff --git a/pkg/document/values.go b/pkg/document/values.go index 760b82f..863d3d4 100644 --- a/pkg/document/values.go +++ b/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 } diff --git a/pkg/helm/chart_info.go b/pkg/helm/chart_info.go index d82d316..9fef30a 100644 --- a/pkg/helm/chart_info.go +++ b/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 diff --git a/pkg/helm/comment.go b/pkg/helm/comment.go index 972fdc0..35b1f3f 100644 --- a/pkg/helm/comment.go +++ b/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])