Avoid the need to prefix value documentation with '---' about helm-docs HOT 13 CLOSED

Whoa there. To answer some of your questions, documenting an array item as you did does work, the key here would be some.thing[0]. To document the whole list, you'd put the comment on the line above thing.

Prefix or not, my hands are tied to some extent by the go yaml.v3 library, so for some of these examples I'm honestly not sure if they'll be picked up. Basically if you do same indentation on the previous line it's always picked up, object, list, whatever.

I'm obviously kind of in the same camp as this last comment. I like the fact that it's explicit, even though it's a little jarring visually. It makes it clear to a new person in a repository that there's something important about these comments and you shouldn't just go change them.

For now I'm gonna leave this open, I'm liking the discussion and I'm hoping for more feedback and I'm too busy at work to do this right now anyway.

from helm-docs.

@norwoodj I'll give it a try!

from helm-docs.

Hey @chgl I agonized over this when working on v1. My thinking in requiring the prefix was that it reflected the intent of the chart author that this comment should be parsed by helm-docs. I was concerned that if I went with this proposed solution users would be surprised occasionally by comments they intended not be parsed as descriptions making their way into a README, e.g.

# This file is auto-formatted with yamlfmt, do not edit without re-running
deployment:
  image: hello:world
  replicas: 23

secret:
  enabled: false
  data: {}

In this case, the top comment would appear as a description for the deployment object, which would get its own row in the values table. Clearly in this case the intent is not for this to be treated as the description.

Of course, this issue could be mitigated by putting a single newline between the comment and the deployment: line, so maybe the prefix requirement is more annoying than the issue it's trying to fix. I don't know.

It's really up to you users. Pulling in all of the contributors:
@sc250024 @RemingtonReackhof @Artus-LHIND @matheusfm @ccremer @simoncaron @rbren @nvtkaszpir @acim @dirtycajunrice

What do y'all think about removing the prefix entirely from doc comments? Please answer in the poll below V

from helm-docs.

from helm-docs.

Since #39 did not make it, I have use cases where I would document an example in values.yaml without having it parsed, especially in cases where empty arrays or objects are "documented" by comments to illustrate an example. Otherwise it would be interpreted as default value, which is wrong.

Having to duplicate each key with # key.subkey -- syntax was annoying indeed. But I'd regard the new # -- syntax as just a minor cosmetic issue now.

from helm-docs.

@norwoodj
What would you suggest to use as an alternative for adding comments that should not get parsed if you remove the prefix requirement?

from helm-docs.

@ccremer my 2 cents: ignore any comment followed by a blank line. Ignore any comment starting with @ignore (or @docignore maybe)

Edit: https://github.com/kubepack/chart-doc-gen uses # Example: to denote sample expressions that should be included in the values table. And +doc-gen:break to skip over nested values.

from helm-docs.

@chgl Please no confusing/hidden features with blank lines 😃 I have already a hard time controlling whitespaces and newlines in Go templates and Jinja2

So basically this proposal is about reversing the comment behaviour: Normal comments get parsed, and special comments have another effect. In that case I'd rather have shorter notation for ignoring comments like ## some-comment. Otherwise documenting a complex example over multiple lines each starting with # @ignore is annoying too.

The # Example approach sounds interesting though. Maybe this could also be combined with the idea to have examples in external, dedicated YAML files to help with parsing examples (see #39 (comment)). Helm docs would then load and parse an additional file and display the contents as example (inline in description, or maybe even it's own section in the readme)

from helm-docs.

@ccremer

Please no confusing/hidden features with blank lines

I feel like in this case it would be far more confusing if an expression like

# Use these values to configure your deployment

some:
  # configure something here
  value: 123

would result in Use these values to configure your deployment documenting the some key.

Similar to # Example, maybe # @ignore could ignore the entire comment block?

from helm-docs.

Well, extending on your example, how would we handle these cases:

# yamllint disable-line rule:key-duplicates

# A comment that has blank lines before and after

some:
  # configure something here
  value: 123
  # an ignored comment, but semantically part of thing:

  # configure another thing
  thing:
  # what if an array is commented
  - arr1
  - arr2
  # what if we have multiple lines, indented, still "belonging" semantically to the content above
# or what if the next line is an empty comment
#
and-some-other-key: {}

I'm actually not sure if some of these cases are already handled regardless of a prefix. @norwoodj might give hints.

I dunno. With a prefix it makes it explicit and crystal clear whether a value is present in the README. Without a prefix, you'd have to know which style of comments have no effect in certain cases. I'd rather favor explicitness so that someone who doesn't know helm-docs can still contribute because the file follows visibly a certain style.

from helm-docs.

At first I also disliked the syntax, but after using it for a couple hours (and reading this issue) I think it's much cleaner than any of the suggested alternatives: it's explicit, no hidden features.

The syntax could potentially be changed to something like #: or #@: it's shorter and less intrusive.

Alternatively, I could imagine a configuration that inverts the comment checking behavior: ignore the ones that start with #: or #@, include everything else.

My 2 cents.

from helm-docs.

From a cursory glance at the source code, maybe it's sufficient to make the comment regex in https://github.com/norwoodj/helm-docs/blob/master/pkg/document/values.go#L33 configurable to allow arbitrary comment prefixes?

from helm-docs.

@chgl I think this is the best answer. I would accept a PR that did as you describe. I unfortunately don't have time to do the work myself at present.

from helm-docs.