Question: Generate the table of the values with sub-sections ?

[cmoulliard]

Question

Is it possible to generate the table of the values as a collection of tables if we define within the values.yaml file the different sections

How it works now

Here is what it is generated by default

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| deployment.containerPort | int | `8080` |  |
...

from the following definition

deployment:
  containerPort: 8080

What I propose

Generate a section level for a yaml root element

## Deployment

Deployment yaml resource containing the parameters to configure the containers, initContainers, volumes, .... 

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| containerPort | int | `8080` |  |

using the following convention:

include a comment : # Section: xxxxx before a root element where the # Section will allow the tool to create a markdown ## Title containing the name of the field defined hereafter = deployment and using xxxxxx as text paragraph.

# Section: Deployment yaml resource containing the parameters to configure the containers, initContainers, volumes, .... 
deployment:
  containerPort: 8080

[j-buczak]

I also would love this feature.

I would propose @section tag to divide all parts into separate sections.

Currently this tag is used by other feature (see example-charts/custom-value-notation-type/README.md) however I think it's misleading. This should be renamed to @raw. I already started working on it: Rename @section to @raw #142

[bluebrown]

Sections would be amazing. Preferable via tag to allow the user grouping themselves like @j-buczak suggests. The suggestion from OP is not optimal IMO, especially stripping the prefix. In the perfect case, you can copy-paste the mentioned values to a --set flag.

BAD

## Deployment

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| containerPort | int | `8080` |  |

Cannot copy and paste key as is, need to manually concatenate.

GOOD

## Deployment

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| deployment.containerPort | int | `8080` |  |

Can copy and paste deployment.containerPort as is. Good UX.

[j-buczak]

For now I added sections for each dependency. This is open for further enhancement for single values file sections (e.g. with @section tag). PR: Add option to add dependency values as subsection #144

[j-buczak]

I added bunch of PRs that are related to this, but not the final one, since currently I have no more time to finish this feature. If somebody wants to pick this up - I stashed my WIP here: https://github.com/j-buczak/helm-docs/tree/WIP_section_in_values

[jessebot]

So this was merged in https://github.com/norwoodj/helm-docs/pull/194 a few months ago, however, you need to comment EVERY value, so example:

current behavior explanation

values.yaml

deployment:
  # -- enable the deployment vs job
  # @section -- Deployment
  enabled: true
  # -- replica count if not using autoscaling
  # @section -- Deployment
  replicaCount: 1

README.go.tmpl

# Sections

This creates values, but sectioned into own section tables if a section comment is provided.

{{ template "chart.valuesSection" . }}

Resulting README.md

# Sections

This creates values, but sectioned into own section tables if a section comment is provided.

## Values

### Deployment

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| deployment.enabled | bool | `true` | enable the deployment vs job |
| deployment.replicaCount | int | `1` | replica count if not using autoscaling |

rendered readme

Sections

This creates values, but sectioned into own section tables if a section comment is provided.

Values

Deployment

Key	Type	Default	Description
deployment.enabled	bool	true	enable the deployment vs job
deployment.replicaCount	int	1	replica count if not using autoscaling

Proposal

values.yaml

Note: you define the section only once at the top of the section, and also a comment for the section in the readme

# -- Parameters related to deployments...
# @section -- Deployment
deployment:
  # -- enable the deployment vs job
  enabled: true
  # -- replica count if not using autoscaling
  replicaCount: 1

Resulting README.md

# Sections

This creates values, but sectioned into own section tables if a section comment is provided.

## Values

### Deployment

Parameters related to deployments...

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| deployment.enabled | bool | `true` | enable the deployment vs job |
| deployment.replicaCount | int | `1` | replica count if not using autoscaling |

rendered readme

Sections

This creates values, but sectioned into own section tables if a section comment is provided.

Values

Deployment

Parameters related to deployments...

Key	Type	Default	Description
deployment.enabled	bool	true	enable the deployment vs job
deployment.replicaCount	int	1	replica count if not using autoscaling

[rvc-mf]

Quick question about the custom @section rendering.

Is there a way to order the sections that are rendered by {{ template "chart.valuesSection" . }}?

Looks like by default it goes with larger (read more elements in the resulting table) first, unless uncategorized (Other values).