Per my comment to @wrenix here:

If we used helm-docs, that would be cool. It looks like they recently added the ability to do sections (which was largely what stopped us being interested in this before)!
https://github.com/norwoodj/helm-docs/tree/master/example-charts/sections

We'd need to prefix each section with the name of the section like:

# @section -- database
postgresql:
# -- enable postgresql sub chart
  enabled: false

See their example values.yaml here:
https://github.com/norwoodj/helm-docs/blob/master/example-charts/sections/values.yaml

But then you get a specific section you can render in the README.md like their example here:

## Values

### database

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| postgresql.enabled | bool | `"false"` | enable postgresql sub chart |

Things to consider

• We would also need a README.gotmpl
  • we would need to import the bulk of the tips and help text in our current readme into the readme template, or it would get deleted anytime someone runs helm-docs
• It would be nice to use a github action to automatically update the docs from the readme. I use gabe565/setup-helm-docs-action for this on my personal repos. It requires a second action with write access to at least contents if you want it to actually commit back it's updated docs it generates.
• There is a pre-commit hook for helm-docs so we could include that in a .pre-commit-config.yml file.

open question

Can you have comments and additional data for specific sections? For instance, right now, we have a database section of our readme that gives further details on the externalDatabase parameter. Is there a way to call the sections in the README.gotmpl?