Generate documentation from comments in the values.yaml file.

[ksuderman]

Includes a very simple script that parses the values.yaml file and generates a markdown (GFM) table with keys that have been documented with a comment starting with the string #- (configurable).

I looked for other programs that could do this (yamldoc, Frigate, and Ruamel.yaml), but they are all sub-optimal for our use case.

Discussion Points

1. Do we want to proceed with this?
2. Does anyone care what string is used to introduce a documentation comment?

I don't think we need, or want to, document every value in the values.yaml file, but I think we do want to document Galaxy specific configuration values.

I have included a VALUES.md file to view the output of the script. The markdown table could be pasted into the README, or the README could link to the VALUES.md file.

[jacobtomlinson]

They there, author of Frigate here. This looks neat. I'd love to know what limitations you ran into with Frigate and how we could've improved things? Was it being able to select the lines you want to document with #- or something else?

[ksuderman]

Hi @jacobtomlinson there were few things I was looking for in a documentation tool.

1. Being able to use a special marker like #- so only the documentation comments are included in the output. This allows us to comment out sections or include comments, examples, etc. that aren't meant to be included as part of the documentation.
2. The documentation comments should be able to span multiple lines and come before the key they are documenting.
3. Only keys that have documentation comments should be included in the output. For example, there are only so many times we need to document that *Probe.enabled enables the [startup|readiness|liveness] probe.

I did the search several months ago, so I don't recall if all of those applied to Frigate, but I wasn't able to find anything that handled all of those cases.

[Editied to add] We would me more than happy to look at Frigate again if it is able to do all of the above.

[jacobtomlinson]

Thanks @ksuderman that's really helpful. You're right that we don't support any of that today, I don't think 1 and 3 would be much of a lift at all. 2 is a little harder due to the way we use Ruamel.yaml but I'm keen to explore it.

[ksuderman]

I don't think any of the tools I looked at handled the second item, and I think that is a function of the way ruamel handles comments. Keep us updated!