Doc comments in values.yaml results in incomplete autogenerated documentation

[voutilad]

What happened?

The reference documentation at https://docs.redpanda.com/current/reference/k-redpanda-helm-spec/#external is incomplete because of the formatting of the comments. Specifically, details on some of the settings under external are missing.

See this section of values.yaml:

helm-charts/charts/redpanda/values.yaml

Lines 263 to 286 in bfb4e55

	# If specified, then it will be appended to the `external.addresses` values as each broker's advertised address
	# domain: local
	# Optional list of addresses that the Redpanda brokers advertise.
	# Provide one entry for each broker in order of StatefulSet replicas.
	# The number of brokers is defined in statefulset.replicas.
	# The values can be IP addresses or DNS names.
	# If external.domain is set, the domain is appended to these values.
	# There is an option to define a single external address for all brokers and leverage
	# prefixTemplate as it will be calculated during initContainer execution.
	# addresses:
	# - redpanda-0
	# - redpanda-1
	# - redpanda-2
	#
	# annotations:
	# For example:
	# cloud.google.com/load-balancer-type: "Internal"
	# service.beta.kubernetes.io/aws-load-balancer-type: nlb
	# If you enable externalDns, each LoadBalancer service instance
	# will be annotated with external-dns hostname
	# matching external.addresses + external.domain
	# externalDns:
	# enabled: true
	# prefixTemplate: ""

What did you expect to happen?

Expectation is all valid settings (e.g. external.domain, external.addresses...) are documented in the reference listing.

How can we reproduce it (as minimally and precisely as possible)?. Please include values file.

n/a

Anything else we need to know?

No response

Which are the affected charts?

Redpanda

Chart Version(s)

Since commit bfb4e55

Cloud provider

n/a

JIRA Link: K8S-125

[chrisseto]

Thanks for catching this! I don't see a diff from the referenced commit that would result in this happening? I think I upgraded the version of the documentation generator at some point around then, perhaps that's what broke this?

@JakeSCahill can you check if this affects the generated docs for the docs website?

[JakeSCahill]

The issue is due to a limitation with the tool we use to generate the docs.

Here's the issue we are tracking: norwoodj/helm-docs#175

[chrisseto]

oooooooh, Thanks for the reference @JakeSCahill !

I think we'd want to use their nil value example in these cases? The generation will look a bit strange but that should get them to show up something like this:

Name	Type	default	Description
external.prefixTemplate	string	""	Example value 123 and here's what that would do

[JakeSCahill]

That does look promising. I'll try this out locally and if it's good I'll submit the PR to fix this issue. thanks @chrisseto