norwoodj/helm-docs

[Bug]: Always failing when using the --documentation-strict-mode flag

Opened this issue · 1 comments

wolfwolker commented

Is there an existing issue for this?

  • I have searched the existing issues

Current Behavior

When the flag is added to the cli, a complete list of the values keys is dumped, no matter the documentation comments present in the values.yaml file, and it exits. No readme file is generated.

Expected Behavior

List only the undocumented keys of values.yaml file if there is any, ignoring the ones tagged with the @ignored keyword.

Steps to reproduce it

  1. Clone https://github.com/norwoodj/helm-docs repository (master)
  2. Navigate to example-charts/best-values-example
  3. rm README.md
  4. docker run --rm --volume "$(pwd):/helm-docs" -u $(id -u) jnorwood/helm-docs:latest helm-docs -x -l trace
  5. This is the output
time="2024-05-09T18:30:36Z" level=debug msg="No ignore file found at .helmdocsignore, using empty ignore rules"
time="2024-05-09T18:30:36Z" level=info msg="Found Chart directories [.]"
time="2024-05-09T18:30:36Z" level=debug msg="Rendering from optional template files [README.md.gotmpl]"
time="2024-05-09T18:30:36Z" level=warning msg="Error parsing information for chart ., skipping: values without documentation: \nstatefulset\nstatefulset.image\nstatefulset.extraVolumes\nstatefulset.extraVolumes.[0].name\nstatefulset.extraVolumes.[0].emptyDir\nstatefulset.livenessProbe\nstatefulset.livenessProbe.enabled\nstatefulset.podLabels\nconfig\nconfig.databasesToCreate\nconfig.usersToCreate\nconfig.usersToCreate.[0].name\nconfig.usersToCreate.[0].admin\nconfig.usersToCreate.[1].name\nconfig.usersToCreate.[1].readwriteDatabases"
time="2024-05-09T18:30:36Z" level=debug msg="Rendering from optional template files [README.md.gotmpl]"
  1. Same command again removing the -x generates a nice and clean README.md and the terminal output is:
time="2024-05-09T18:30:57Z" level=debug msg="No ignore file found at .helmdocsignore, using empty ignore rules"
time="2024-05-09T18:30:57Z" level=info msg="Found Chart directories [.]"
time="2024-05-09T18:30:57Z" level=debug msg="Rendering from optional template files [README.md.gotmpl]"
time="2024-05-09T18:30:57Z" level=debug msg="Rendering from optional template files [README.md.gotmpl]"
time="2024-05-09T18:30:57Z" level=info msg="Generating README Documentation for chart ."
time="2024-05-09T18:30:57Z" level=debug msg="Did not find template file README.md.gotmpl for chart ., using default template"
time="2024-05-09T18:30:57Z" level=debug msg="Using template files [README.md.gotmpl] for chart ."

I've tried versions from 1.11.0 to latest in docker, and the latest macos binary installed with homebrew, always with same result.

Reference Chart

example-charts/best-values-example present in the helm-docs repository.

Reference Template

No response

Environment

  • Docker image
    • 1.11.2
    • 1.11.3
    • 1.13.3
    • latest
  • homebrew package

Link to helm-docs Logs

No response

Further Information

No response

dackroyd commented

Encountered this myself today while trying to setup strict checks for chart documentation. After a bit of trawling through changes, I loaded it up locally in the debugger.

While stepping through, I discovered that this appears to be an issue relating to parsing of the values descriptions. Specifically, the parsing expects the "old" metadata format, where the leading part of the doc comment includes the field path. If omitting this (using the newer style), the parsing finds no match on the key, so skips adding it to the keyToDescriptions map (match[1] is "" due to their being no explicit key in the comment), and the strict documentation check isn't aware of it, so fails.

helm-docs/pkg/helm/chart_info.go

Lines 260 to 268 in c6e5e3b

if !foundValuesComment {
match := valuesDescriptionRegex.FindStringSubmatch(currentLine)
if len(match) < 3 || match[1] == "" {
continue
}
foundValuesComment = true
commentLines = append(commentLines, currentLine)
continue
}

When the documentation is rendered however, parsing of comments does not skip when this is missing, it gets an empty string:

helm-docs/pkg/helm/comment.go

Lines 29 to 39 in c6e5e3b

for i := range commentLines {
match := valuesDescriptionRegex.FindStringSubmatch(commentLines[i])
if len(match) < 3 {
continue
}
valueKey = match[1]
c.Description = match[2]
docStartIdx = i
break
}

This is used as the "auto description" if there isn't an explicit mapping in keyToDescriptions, and ultimately used to render the docs.

  • 👍2