Chart docs

[keyvaann]

Here is the template that we can use to generate documentation for charts.
This is created via helm-docs. It reads values description from values.yaml and other information from README.md.gotmpl and Chart.yaml files. We can also add custom general templates like the one defined in _templates.gotmpl files.

To generate the README.md files I ran this command from main directory of repository:

helm-docs -s file --template-files=./_templates.gotmpl --template-files=README.md.gotmpl

We can add the helm-docs command as a Pre-commit hook but it does depend on the developer to install it on their machine and make sure to configure it. I prefer if we have a CI test for it as well to check for this.

[keyvaann]

There a 2 other alternatives for helm-docs and we can consider them as well if this approach doesn't work for us:
https://github.com/kubepack/chart-doc-gen
https://github.com/bitnami-labs/readme-generator-for-helm

[nivemaham]

I like the idea. Although, I think the value.yaml are usually auto generated with some k8s specific configs which I am not sure if we should document. I think the application specific ones make sense. So starting from postgres.*

Is there anyway (probably with custom template) we can control this.
In any case, we still have to document each values on value.yaml.

[keyvaann]

For the default values from values.yaml we can define them once and copy them to other charts.

[blootsvoets]

The setup with helm-docs looks good to me. We could opt for a few more defaults templates, like how you use the RADAR-Kubernetes repo, and add a per-chart more detailed usage instruction (e.g. when to use certain config settings, etc.)

The oauth client config is very verbose now, but from the readme https://github.com/norwoodj/helm-docs#markdown-rendering looks like it is possible to modify the comments such that not all values are shown.

[blootsvoets]

Never mind, it's not possible to skip values. chart-doc-gen is not well-documented, I suggest we skip that. https://github.com/bitnami-labs/readme-generator-for-helm looks the most mature, but it does not support tempating the other sections out of the box, it just templates the values documentation. Also it is much more verbose. In all, I think helm-docs is a fine choice.

[nivemaham]

Alright. My first choice is helm-docs as well. I think we have a decision on the tool.

[keyvaann]

@blootsvoets we can split oauth client config into another values file so it won't be read by helm-docs but we manually create the documentation for it

[nivemaham]

@K1Hyve I think that makes sense. If you can split them into another values, I can do the documentation.

[keyvaann]

@nivemaham you can start documenting values in this chart and other charts if you have time and I'll separating the values file next week

[nivemaham]

@K1Hyve Yes. Will do. 👍

[keyvaann]

@nivemaham Now you can add MP specific documents.

For details on how to configure OAuth client you can add them to DOCS.md.gotmpl

Use make gen to generate the README.md again.

[github-actions]

Great PR! Please pay attention to the following items before merging:

Files matching charts/*/values.yaml:

• Is the PR adding a new container? Please reviewer, add it to the models (internal process)
• Is the PR adding a new parameter? Please, ensure it’s documented in the README.md

This is an automatically generated QA checklist based on modified files

[nivemaham]

LGTM. I think we can merge. We can review again, when Joris is back with all of the changes done before merging to master.