search

vinzscam / backstage-chart

Backstage Helm Chart
27 stars 10 forks source link

Use of Automatic Helm Docs Generator #3

Closed ChrisJBurns closed 1 year ago

ChrisJBurns commented 2 years ago

Something trivial but easy and effective. Have used helm-docs before to automatically generate the Helm documentation based on comments. Worth adding?

cmoulliard commented 2 years ago

As currently, your values file already includes @Section, @Param annotations, can you tell us if you use a tool to populate the tables containing the parameters of the README.md markdown file ? Which one ?

vinzscam commented 2 years ago

As currently, your values file already includes @Section, @Param annotations, can you tell us if you use a tool to populate the tables containing the parameters of the README.md markdown file ? Which one ?

yeah they annotations are there because I was thinking about using readme-generator-for-helm but I haven't set up yet. So, right now the documentation isn’t automatically generated.

Does anyone have more hands on experience on the pros and cons of both tools?

cmoulliard commented 2 years ago

helm-docs is a super powerful tool but it lacks the feature to aggregate values/parameters (= a table) under different sections : https://github.com/norwoodj/helm-docs/issues/97

Se we cannot currently generate something like this 

## Section 1

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| containerPort | int | `8080` | blablabla |
ChrisJBurns commented 2 years ago

Which ever one is best is good for me. I only said helm-docs as I've used it on another Chart. This issue was moreso around getting automatic documentation generation as opposed to using helm-docs. In fact, I shall change the title to be a bit more generic.

cmoulliard commented 2 years ago

This issue was moreso around getting automatic documentation generation as opposed to using helm-docs

Could we add this process generating the doc part of the github action - helm release or helm snapshot. WDYT ? @vinzscam

vinzscam commented 2 years ago

This issue was moreso around getting automatic documentation generation as opposed to using helm-docs

Could we add this process generating the doc part of the github action - helm release or helm snapshot. WDYT ? @vinzscam

absolutely, good call.