From 26ccfc85ec31e91479d41e4e690b7394a94e8291 Mon Sep 17 00:00:00 2001 From: Antoine C Date: Mon, 8 Jul 2024 19:49:50 +0100 Subject: [PATCH] fix: restore support for ignored yaml comment --- README.md | 18 ++++++++ example-charts/comment-ignored/Chart.yaml | 10 +++++ example-charts/comment-ignored/README.md | 29 +++++++++++++ example-charts/comment-ignored/values.yaml | 15 +++++++ example-charts/no-requirements/README.md | 6 +-- pkg/document/values_test.go | 49 ++++++++++++++++++++++ pkg/helm/comment.go | 5 +++ 7 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 example-charts/comment-ignored/Chart.yaml create mode 100644 example-charts/comment-ignored/README.md create mode 100644 example-charts/comment-ignored/values.yaml diff --git a/README.md b/README.md index 4522e02..60c6294 100644 --- a/README.md +++ b/README.md @@ -425,6 +425,24 @@ configMap: not real config param: value ``` +### Ignored YAML comments + +In cases you would like to not include certain YAML comments, such as explicit example, context information, you me use a double `#` to tell helm-docs to ignore e.g. + +```yaml + # -- Using existing secret + ## Secret format: + ## stringData: + ## comm_config.yaml: | + ## communications: + ## # Here specify settings for each app, like Slack, Mattermost etc. + ## # NOTE: Use setting format visible below. + ## + ## FIXME some keys needs stuff to happen. See #1234 + # @default -- an empty string, meaning no existing secret + existingSecretName: "" +``` + ### Advanced table rendering Some helm chart `values.yaml` uses complicated structure for the key/value pairs. For example, it may uses a multiline string of Go template text instead diff --git a/example-charts/comment-ignored/Chart.yaml b/example-charts/comment-ignored/Chart.yaml new file mode 100644 index 0000000..c001e96 --- /dev/null +++ b/example-charts/comment-ignored/Chart.yaml @@ -0,0 +1,10 @@ +apiVersion: v1 +name: comment-ignored +description: A simple chart that installs, let's say PrometheusRules, that contains values.yaml comment that shouldn't be included in the helm-docs +version: "0.2.0" +home: "https://github.com/norwoodj/helm-docs/tree/master/example-charts/comment-ignored" +sources: ["https://github.com/norwoodj/helm-docs/tree/master/example-charts/comment-ignored"] +engine: gotpl +maintainers: + - email: norwood.john.m@gmail.com + name: John Norwood diff --git a/example-charts/comment-ignored/README.md b/example-charts/comment-ignored/README.md new file mode 100644 index 0000000..fd32f75 --- /dev/null +++ b/example-charts/comment-ignored/README.md @@ -0,0 +1,29 @@ +# no-requirements + +![Version: 0.2.0](https://img.shields.io/badge/Version-0.2.0-informational?style=flat-square) + +A simple chart that installs, let's say PrometheusRules, that needs no sub-charts + +**Homepage:** + +## Maintainers + +| Name | Email | Url | +| ---- | ------ | --- | +| John Norwood | | | + +## Source Code + +* + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| rules.latency.percentiles.99.duration | string | `"5m"` | Duration for which the 99th percentile must be above the threshold to alert | +| rules.latency.percentiles.99.threshold | float | `1.5` | Threshold in seconds for our 99th percentile latency above which the alert will fire | +| rules.statusCodes.codes.5xx.duration | string | `"5m"` | Duration for which the percent of 5xx responses must be above the threshold to alert | +| rules.statusCodes.codes.5xx.threshold | float | `1.5` | Threshold percentage of 5xx responses above which the alert will fire | + +---------------------------------------------- +Autogenerated from chart metadata using [helm-docs v1.14.0](https://github.com/norwoodj/helm-docs/releases/v1.14.0) diff --git a/example-charts/comment-ignored/values.yaml b/example-charts/comment-ignored/values.yaml new file mode 100644 index 0000000..f79764d --- /dev/null +++ b/example-charts/comment-ignored/values.yaml @@ -0,0 +1,15 @@ +rules: + latency: + percentiles: + "99": + # rules.latency.percentiles.99.threshold -- Threshold in seconds for our 99th percentile latency above which the alert will fire + ## Note that this is a secret comment that should be added to the doc + threshold: 1.5 + # rules.latency.percentiles.99.duration -- Duration for which the 99th percentile must be above the threshold to alert + ## Secret format: + ## stringData: + ## comm_config.yaml: | + ## communications: + ## # Here specify settings for each app, like Slack, Mattermost etc. + ## # NOTE: Use setting format visible below. + duration: 5m \ No newline at end of file diff --git a/example-charts/no-requirements/README.md b/example-charts/no-requirements/README.md index fd32f75..4ada58f 100644 --- a/example-charts/no-requirements/README.md +++ b/example-charts/no-requirements/README.md @@ -1,10 +1,10 @@ -# no-requirements +# comment-ignored ![Version: 0.2.0](https://img.shields.io/badge/Version-0.2.0-informational?style=flat-square) A simple chart that installs, let's say PrometheusRules, that needs no sub-charts -**Homepage:** +**Homepage:** ## Maintainers @@ -14,7 +14,7 @@ A simple chart that installs, let's say PrometheusRules, that needs no sub-chart ## Source Code -* +* ## Values diff --git a/pkg/document/values_test.go b/pkg/document/values_test.go index fc7796a..0a1dbde 100644 --- a/pkg/document/values_test.go +++ b/pkg/document/values_test.go @@ -1304,6 +1304,55 @@ animals: assert.Equal(t, "The best kind of animal probably, allow me to list their many varied benefits. Cats are very funny, and quite friendly, in almost all cases", valuesRows[0].AutoDescription) } +func TestIgnoredCommentDescription(t *testing.T) { + helmValues := parseYamlValues(` +animals: + # -- The best kind of animal probably, allow me to list their many varied benefits. + # Cats are very funny, and quite friendly, in almost all cases + ## They can be dangerous sometimes + ## especially when untamed! + # @default -- The list of cats that _I_ own + cats: + - echo + - foxtrot + ## This one, you probable don't want to + ## meet them face to face + - cobra + ## They are always cute + # Little doggo + dogs: + - alpha + ## Maybe this one not that much + - beta +`) + + valuesRows, err := getSortedValuesTableRows(helmValues, make(map[string]helm.ChartValueDescription)) + + assert.Nil(t, err) + assert.Len(t, valuesRows, 3) + + assert.Equal(t, "animals.cats", valuesRows[0].Key) + assert.Equal(t, listType, valuesRows[0].Type) + assert.Equal(t, "The list of cats that _I_ own", valuesRows[0].AutoDefault) + assert.Equal(t, "", valuesRows[0].Default) + assert.Equal(t, "", valuesRows[0].Description) + assert.Equal(t, "The best kind of animal probably, allow me to list their many varied benefits. Cats are very funny, and quite friendly, in almost all cases", valuesRows[0].AutoDescription) + + assert.Equal(t, "animals.dogs[0]", valuesRows[1].Key) + assert.Equal(t, stringType, valuesRows[1].Type) + assert.Equal(t, "", valuesRows[1].AutoDefault) + assert.Equal(t, "`\"alpha\"`", valuesRows[1].Default) + assert.Equal(t, "", valuesRows[1].Description) + assert.Equal(t, "", valuesRows[1].AutoDescription) + + assert.Equal(t, "animals.dogs[1]", valuesRows[2].Key) + assert.Equal(t, stringType, valuesRows[2].Type) + assert.Equal(t, "", valuesRows[2].AutoDefault) + assert.Equal(t, "`\"beta\"`", valuesRows[2].Default) + assert.Equal(t, "", valuesRows[2].Description) + assert.Equal(t, "", valuesRows[2].AutoDescription) +} + func TestAutoMultilineDescriptionWithoutValue(t *testing.T) { helmValues := parseYamlValues(` animals: diff --git a/pkg/helm/comment.go b/pkg/helm/comment.go index f8b17b4..6bb996e 100644 --- a/pkg/helm/comment.go +++ b/pkg/helm/comment.go @@ -74,6 +74,11 @@ func ParseComment(commentLines []string) (string, ChartValueDescription) { commentContinuationMatch := commentContinuationRegex.FindStringSubmatch(line) + // If the comment uses a double hash, this means it should be ignored for the documentation + if len(line) > 2 && line[1] == '#' { + continue + } + if isRaw { if len(commentContinuationMatch) > 1 {