Discussion: state of helm-docs for generating sectioned documentation

[jessebot]

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?

[wrenix]

I am fine with it, so every value option should be uncommented with an empty value to get it in the docs: https://github.com/nextcloud/helm/pull/534#discussion_r1485699750

(maybe you do not need any custom README.md.gotmpl just overwrite the default template for the chapter)

---

your question: i do not know it, but i believe a [database](#database) could work.

[wrenix]

i start to work on a migration here: https://github.com/nextcloud/helm/pull/633 there is a lot of todo, so do not be shy to add some commits here