Upgrade helm-docs

[jmeridth]

Is your feature request related to a problem?

no

Related helm chart

argo-cd, argo-events, argo-rollouts, argo-workflows, argocd-image-updater, argocd-apps

Describe the solution you'd like

Upgrade the scripts/helm-docs.sh file to use the latest jnorwood/helm-docs container image (currently 1.11.0). The current issue is that comments have to be reformatted in our README.md.gotmpl files so that they don't show up in the generated README.md files. That is mentioned here in its README.

Describe alternatives you've considered

not upgrading

Additional context

Was going to be a part of #1782 but ended up being beyond the scope of the PR.

[pdrastil]

Not possible to use ## - ref norwoodj/helm-docs#148

[jmeridth]

@pdrastil yep. That's mentioned above. From the helm-docs README

New-style comments are much the same as
the old-style comments, except that while old comments
for a field could appear anywhere in the file,
new-style comments must appear on the line(s)
immediately preceding the field being documented.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[jmeridth]

Not stale

[jdvgh]

I had a look into the code of helm-docs but apparently comments on the next lines are just concatenated with a space:
https://github.com/norwoodj/helm-docs/blob/7717a245cecabec154eccc0e9f7dbc43fb514754/pkg/helm/comment.go#L78-L80

See also here:
https://github.com/norwoodj/helm-docs/blob/master/README.md?plain=1#L252-L253

Note that comments can continue on the next line. In that case leave out the double dash, and the lines will simply be appended with a space in-between, as in the controller.replicas field in the example above

If they were at least combined with a newline, we would be able to parse \n# as a comment. However, with spaces this is not possible in my opinion (as # could also be used inside a comment, and then we would not "catch" the first comment started with ## ).

I tinkered a little bit with e.g. the clusterCredentials in the argo-cd values:

values.yaml

configs:
  # -- Provide one or multiple [external cluster credentials]
  # @default -- `[]` (See [values.yaml])
  ## Ref:
  ## - https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#clusters
  ## - https://argo-cd.readthedocs.io/en/stable/operator-manual/security/#external-cluster-credentials
  ## - https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#project-scoped-repositories-and-clusters
  clusterCredentials: []

README.md.gotmpl

{{- range .Values }}
  {{- if hasPrefix "configs.clusterCredentials" .Key }}
    {{-  splitList " #" .AutoDescription }}
  {{- end }}
{{- end }}

result of running ./scripts/helm-docs.sh in README.md

5

So we got all 5 lines, but I don't know if this is stable enough to really implement - there could be quite a few edge cases; at least in contrast to just continue using the old version.

For reference, when just printing the AutoDescription we get the following:
README.md.gotmpl

{{- range .Values }}
  {{- if hasPrefix "configs.clusterCredentials" .Key }}
    {{-  .AutoDescription }}
  {{- end }}
{{- end }}

result of running ./scripts/helm-docs.sh in README.md

Provide one or multiple [external cluster credentials] # Ref: # - https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#clusters # - https://argo-cd.readthedocs.io/en/stable/operator-manual/security/#external-cluster-credentials # - https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#project-scoped-repositories-and-clusters

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.