The helm2readme tool auto-generates documentation from helm charts into 'README' markdown files. The resulting files contain metadata about their respective chart and a table with each of the chart's values, their defaults, and an optional description parsed from comments.
The markdown generation is entirely gotemplate-driven (currently). helm2readme parses metadata from charts and generates a number of sub-templates that can be referenced in a template file (by default README.md.gotmpl).
If no template file is provided, helm2readme has a default internal template that will generate a reasonably formatted README.
- Documentation Generation: Automatically generates documentation from Helm charts into markdown files.
- Metadata Inclusion: Provides comprehensive metadata about charts and their corresponding values.
- Comment Parsing: Parses descriptions and default values from comments in Helm charts.
- Template-Driven: Utilizes gotemplate for markdown generation (Currently).
- Custom CSS: Allows the addition of custom CSS for each element in tables, including entire tables or specific rows.
- Global CSS: Enables the application of global CSS to all elements in all tables.
- Table Manipulation: Transfers and reorders tables to sections of your choice.
- Chart Directory Exclusion: Supports the use of
.helmdocsignorefiles to ignore specific chart directories. - Subdirectory Search: Facilitates the auto-search for charts in subdirectories using the
--chart-search-rootflag. - Table Ordering: Provides table ordering options by key, type, default, or description using the
--order-byflag.
- Ignoring Elements: Introduces the capability to ignore elements or entire tables using the
@ignoretag. - File Inclusion: Enables loading different files inside the Go template for more flexibility.
- Direct Go Template Rendering: Allows rendering of direct Go templates for advanced customization.
- Column Navigation: Links each column name to the corresponding data line in the source file.
- Default Values: You dont have to provide defult value every time ou can add comment that represent the default value by
@default.
The most useful aspect of this tool is the auto-detection of field descriptions from comments:
# -- Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files
statefulset:
image:
# -- Imeeeeeage to use for deploying, must support an entrypoint which creates users/databases from appropriate config files
# -- [section=global] Image to use for depeeloying, must support an entrypoint which creates users/databases from appropriate config files
repository: jnorwood/postgresq
tag: "11"
# -- Additional volumes to be mounted into the database container
extraVolumes:
# this is commeooooooooooooontc
- name: data
emptyDir: {}
emptyDisr: {}
# this is comment
emptyDisqr: {}
# -- Configure the healthcheck for the database
livenessProbe:
enabled: false
# -- The labels to be applied to instances of the database
podLabels: {}Resulting in a resulting README section like so:
Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files
| Key | Type | Default | Description |
|---|---|---|---|
| statefulset | dict | `{'image': {'repository': 'jnorwood/postgresq', 'tag': '11'}, 'extraVolumes': [{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}], 'livenessProbe': {'enabled': False}, 'podLabels': {}}` |
|
| statefulset.image | dict | `{'repository': 'jnorwood/postgresq', 'tag': '11'}` | |
| statefulset.image.repository | str | `jnorwood/postgresq` |
|
| statefulset.image.tag | str | `11` | |
| statefulset.extraVolumes | list | `[{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}]` |
|
| statefulset.extraVolumes[0] | dict | `{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}` | |
| statefulset.livenessProbe | dict | `{'enabled': False}` |
|
| statefulset.livenessProbe.enabled | bool | `False` | |
| statefulset.podLabels | dict | `{}` |
|
You may observe that certain intricate fields (lists and dictionaries) are documented, while others are not. Additionally, simple fields such as statefulset.image.tag are documented even in the absence of a description comment. The criteria determining what gets documented in the final table and what does not will be elaborated on later in this document.
helm2readme can be installed using pip:
pip install helm2readmeTo build from source in this repository:
git clone https://github.com/tactful-ai/helm2readme
cd helm2readme
python setup.py sdist bdist_wheel
pip install .In addition to installing it as a Python package from PyPI, helm2readme also comes as a static 0-dependency self-contained executable and as a docker image. The executables for all 3 operating systems is in the releases section and the docker image's tag is helm2readme:latest.
docker run --rm -v ./Helm-files-location:/app waer/helm2readme:latestTo run and generate documentation into READMEs for all helm charts within or recursively contained by a directory:
helm2readme
# OR
helm2readme --dry-run # prints generated documentation to stdout rather than modifying READMEsThe tool searches recursively through subdirectories of the current directory for Chart.yaml files and generates documentation for every chart that it finds.
It's sometimes necessary to fetch a binary, run it, and remove it in the same command. This would be the case for example if you want to run helm2readme in a clean AWS machine or in Github actions. The following commands will do this:
wget <binary-url> && chmod +x helm2readme && ./helm2readme <args> && rm helm2readmeInvoke-WebRequest -Uri <binary-url> -Out helm2readme.exe;
Start-Process -FilePath ./helm2readme.exe -ArgumentList arg1,arg2,...,argn;
Remove-Item helm2readme.exeWhere the binary url can be obtained by choosing a suitable binary in the releases section of this github and right-clicking then choosing "copy link" or "copy link address". It's a URL that starts with "https://github.com/tactful-ai/helm2readme/releases/download/" and ends with "helm2readme" or "helm2readme.exe" for windows. arg1,arg2,arg3 is how you pass parameters to the binary as you're starting it with Start-Process on windows, where switches are seperate arguments (e.g. -c, helmfolder; is how you point the binary to helmfolder as the chart search root).
The helm2readme tool supports a .helmdocsignore file, similar to a .gitignore file, where you can specify directories to be excluded from the chart search process. This feature allows you to ignore directories that might contain multiple charts or unrelated files, ensuring that only the desired charts are processed. You can also directly reference the Chart.yaml file for a specific chart to prevent it from being processed.
By using the .helmdocsignore file, you have the flexibility to tailor the chart search process to your project's structure and requirements. This is particularly useful when you want to focus on specific charts and exclude others that are not relevant for documentation generation.
When utilizing the helm2readme tool, it's crucial to be mindful of two essential parameters. The first parameter, --chart-search-root, designates the root directory from which the tool will conduct a recursive search for charts to generate documentation for. The second parameter, --template-files, specifies a list of gotemplate files that should be employed in crafting the resulting markdown file for each discovered chart. By default, the values for these parameters are --chart-search-root=. and --template-files=README.md.gotmpl.
Should you provide a template file using just its filename, this indicates that the file should be interpreted as being relative to each individual chart directory found. Conversely, if a template file is provided as a relative path, such as in the form of --template-files=./_templates.gotmpl --template-files=README.md.gotmpl, then it is interpreted as being relative to the chart-search-root. This level of flexibility enables you to adapt the template usage according to the specific location and structure of your chart directories.
This repo is a good example of this in action. If you take a look at the .pre-commit-config.yaml file here, you'll see our search root is set to example-charts and the list of templates used for each chart is the _templates.gotmpl file in that directory and the README.md.gotmpl file in each chart directory.
If any of the specified template files is not found for a chart (you'll notice most of the example charts do not have a README.md.gotmpl) file, then the internal default template is used instead.
In addition to extra defined templates you specify in these template files, there are quite a few built-in templates that can be used as well:
| Name | Description |
|---|---|
| chart.header | The main heading of the generated markdown file |
| chart.name | The name field from the chart's Chart.yaml file |
| chart.deprecationWarning | A deprecation warning which is displayed when the deprecated field from the chart's Chart.yaml file is true |
| chart.description | A description line containing the description field from the chart's Chart.yaml file, or "" if that field is not set |
| chart.version | The version field from the chart's Chart.yaml file |
| chart.versionBadge | A badge stating the current version of the chart |
| chart.type | The type field from the chart's Chart.yaml file |
| chart.typeBadge | A badge stating the current type of the chart |
| chart.appVersion | The appVersion field from the chart's Chart.yaml file |
| chart.appVersionBadge | A badge stating the current appVersion of the chart |
| chart.homepage | The home link from the chart's Chart.yaml file, or "" if that field is not set |
| chart.homepageLine | A text line stating the current homepage of the chart |
| chart.maintainersHeader | The heading for the chart maintainers section |
| chart.maintainersTable | A table of the chart's maintainers |
| chart.maintainersSection | A section headed by the maintainersHeader from above containing the maintainersTable from above or "" if there are no maintainers |
| chart.sourcesHeader | The heading for the chart sources section |
| chart.sourcesList | A list of the chart's sources |
| chart.sourcesSection | A section headed by the sourcesHeader from above containing the sourcesList from above or "" if there are no sources |
| chart.kubeVersion | The kubeVersion field from the chart's Chart.yaml file |
| chart.kubeVersionLine | A text line stating the required Kubernetes version for the chart |
| chart.requirementsHeader | The heading for the chart requirements section |
| chart.requirementsTable | A table of the chart's required sub-charts |
| chart.requirementsSection | A section headed by the requirementsHeader from above containing the kubeVersionLine and/or the requirementsTable from above or "" if there are no requirements |
| chart.valuesHeader | The heading for the chart values section |
| chart.valuesTable | A table of the chart's values parsed from the values.yaml file (see below) |
| chart.valuesSection | A section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no values |
The default internal template mentioned above uses many of these and looks like this:
{{ template "chart.header" . }}
{{ template "chart.deprecationWarning" . }}
{{ template "chart.badgesSection" . }}
{{ template "chart.description" . }}
{{ template "chart.homepageLine" . }}
{{ template "chart.maintainersSection" . }}
{{ template "chart.sourcesSection" . }}
{{ template "chart.requirementsSection" . }}
{{ template "chart.valuesSection" . }}
The tool also includes the internal comment parser, so those functions can be used in the templates you supply.
This tool can parse descriptions and defaults of values from values.yaml files. The defaults are pulled directly from
the yaml in the file.
controller:
publishService:
# -- Whether to expose the ingress controller to the public world
enabled: false
# -- Number of nginx-ingress pods to load balance between.
# Do not set this below 2.
replicas: 2I invite you to check out the example-charts to see how this is done in practice. The but-auto-comments examples in particular document the new comment format.
Note that comments is only for the line that start with # -- . In that case leave out the double dash, and the lines will simply be appended with a space in-between, as in the controller.replicas field in the example above
The following rules are used to determine which values will be added to the values table in the README:
- By default, only leaf nodes, that is, fields of type
int,string,float,bool, empty lists, and empty maps are added as rows in the values table. These fields will be added even if they do not have a description comment - Lists and maps which contain elements will be added as rows in the values table. comment which refers to them
e.g. In this case, both livenessProbe and livenessProbe.httpGet.path will be added as rows in
the values table, also livenessProbe.httpGet.port will be added
# -- Configure the healthcheck for the ingress controller
livenessProbe:
httpGet:
# -- This is the liveness check endpoint
path: /healthz
port: httpResults in:
| Key | Type | Default | Description |
|---|---|---|---|
| livenessProbe | dict | `{'httpGet': {'path': '/healthz', 'port': 'http'}}` |
|
| livenessProbe.httpGet | dict | `{'path': '/healthz', 'port': 'http'}` | |
| livenessProbe.httpGet.path | str | `/healthz` |
|
| livenessProbe.httpGet.port | str | `http` |
you can add css for one table or element in table or even for add tables in the values section by adding @customcss tag to the start of table.
and for each single css that can be added to the table or element in table or even for add tables in the values section by adding -- {the css you want} tag to the start of table.
# -- @custom_css {color: red;}
# -- hello
# -- {text-align: right;}
controller:
name: controller
# -- {color: purple;}
image:
repository: nginx-ingress-controller
tag: "18.0831"and the result aable will be look like that:
hello
| Key | Type | Default | Description |
|---|---|---|---|
| controller | dict | `{'name': 'controller', 'image': {'repository': 'nginx-ingress-controller', 'tag': '18.0831'}, 'persistentVolumeClaims': [], 'extraVolumes': [{'name': 'config-volume', 'configMap': {'name': 'nginx-ingress-config'}}], 'ingressClass': 'nginx'}` |
|
| controller.name | str | `controller` | |
| controller.image | dict | `{'repository': 'nginx-ingress-controller', 'tag': '18.0831'}` | |
| controller.image.repository | str | `nginx-ingress-controller` | |
| controller.image.tag | str | `18.0831` |
You can easily divide your tables into logical sections and reorder them by adding a [] tag at the start of the table's comment. This action will relocate the table to the desired section and allow you to reorder it according to your preference. This approach enables you to effectively organize and structure the tables within the values section, aligning with your desired logical order.
You should take care of transfering table since it executes in order of less . that mean big section will be transfered before the small one.
# -- [section-main]
statefulset:
image:
# -- Imeeeeeage to use for deploying, must support an entrypoint which creates users/databases from appropriate config files
repository: jnorwood/postgresq
tag: "11"it will be rendered as follow:
Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files
| Key | Type | Default | Description |
|---|---|---|---|
| statefulset | dict | `{'image': {'repository': 'jnorwood/postgresq', 'tag': '11'}, 'extraVolumes': [{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}], 'livenessProbe': {'enabled': False}, 'podLabels': {}}` |
|
| statefulset.image | dict | `{'repository': 'jnorwood/postgresq', 'tag': '11'}` | |
| statefulset.image.repository | str | `jnorwood/postgresq` |
|
| statefulset.image.tag | str | `11` | |
| statefulset.extraVolumes | list | `[{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}]` |
|
| statefulset.extraVolumes[0] | dict | `{'name': 'data', 'emptyDir': {}, 'emptyDisr': {}, 'emptyDisqr': {}}` | |
| statefulset.livenessProbe | dict | `{'enabled': False}` |
|
| statefulset.livenessProbe.enabled | bool | `False` | |
| statefulset.podLabels | dict | `{}` |
|
every colum key is link to his line in the values file which ease the process of editing and reaching out the keys using the docuemntation. example of the link:
| Key | Type | Default | Description |
|---|---|---|---|
| dict | `{'httpGet': {'path': '/healthz', 'port': 'http'}}` | ||
| dict | `{'path': '/healthz', 'port': 'http'}` | ||
| str | `/healthz` |
| |
| str | `http` |
If you would like to define a key for a value, but leave the default empty, you can still specify a description for it as well as a type. This is possible with both the old and the new comment format:
controller:
# -- (int) Number of nginx-ingress pods to load balance between
replicas:
# controller.image -- (string) Number of nginx-ingress pods to load balance between
image:This could be useful when wanting to enforce user-defined values for the chart, where there are no sensible defaults.
In cases where you do not want to include the default value from values.yaml, or where the real default is calculated
inside the chart, you can change the contents of the column like so:
service:
# -- Add annotations to the service, this is going to be a long comment across multiple lines
# but that's fine, these will be concatenated and the @default will be rendered as the default for this field
# @default -- the chart will add some internal annotations automatically
annotations: []See here for an example.
In cases you would like to ignore certain values, you can mark it with @ignored tag:
# @ignored
service:
port: 8080