A tool for automatically generating markdown documentation for helm charts
A tool for automatically generating markdown documentation for helm charts
The helm-docs tool auto-generates documentation from helm charts into 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. The tool 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, the tool has a default internal template that will generate a reasonably formatted README.
The most useful aspect of this tool is the auto-detection of field descriptions from comments:
…Resulting in a resulting README section like so:
| Key | Type | Default | Description |
|---|---|---|---|
| config.databasesToCreate[0] | string | "postgresql" |
default database for storage of database metadata |
| config.databasesToCreate[1] | string | "hashbash" |
database for the hashbash project |
| config.usersToCreate[0] | object | {"admin":true,"name":"root"} |
admin user |
| config.usersToCreate[1] | object | {"name":"hashbash","readwriteDatabases":["hashbash"]} |
user with access to the database with the same name |
| statefulset.extraVolumes | list | [{"emptyDir":{},"name":"data"}] |
Additional volumes to be mounted into the database container |
| statefulset.image.repository | string | "jnorwood/postgresql:11" |
Image to use for deploying, must support an entrypoint which creates users/databases from appropriate config files |
| statefulset.image.tag | string | "18.0831" |
You'll notice that some complex fields (lists and objects) are documented while others aren't, and that some simple fields
like statefulset.image.tag are documented even without a description comment. The rules for what is and isn't documented in
the final table will be described in detail later in this document.
helm-docs can be installed using homebrew:
brew install norwoodj/tap/helm-docsor scoop:
scoop install helm-docsor mise:
mise use -g helm-docs@latestThis will download and install the latest release of the tool.
To build from source in this repository:
cd cmd/helm-docs
go buildOr install from source:
go install github.com/norwoodj/helm-docs/cmd/helm-docs@latestIf you want to automatically generate README.md files with a pre-commit hook, make sure you
install the pre-commit binary, and add a .pre-commit-config.yaml file
to your project. Then run:
pre-commit install
pre-commit install-hooksFuture changes to your chart's requirements.yaml, values.yaml, Chart.yaml, or README.md.gotmpl files will cause an update to documentation when you commit.
There are several variants of pre-commit hooks to choose from depending on your use case.
helm-docs Uses helm-docs binary located in your PATH---
repos:
- repo: https://github.com/norwoodj/helm-docs
rev: ""
hooks:
- id: helm-docs
args:
# Make the tool search for charts only under the `charts` directory
- --chart-search-root=charts
helm-docs-built Uses helm-docs built from code in git---
repos:
- repo: https://github.com/norwoodj/helm-docs
rev: ""
hooks:
- id: helm-docs-built
args:
# Make the tool search for charts only under the `charts` directory
- --chart-search-root=charts
helm-docs-container Uses the container image of helm-docs:latest---
repos:
- repo: https://github.com/norwoodj/helm-docs
rev: ""
hooks:
- id: helm-docs-container
args:
# Make the tool search for charts only under the `charts` directory
- --chart-search-root=charts
helm-docs container to a specific tag, follow the example below:---
repos:
- repo: https://github.com/norwoodj/helm-docs
rev: ""
hooks:
- id: helm-docs-container
entry: jnorwood/helm-docs:x.y.z
args:
# Make the tool search for charts only under the `charts` directory
- --chart-search-root=charts
To run and generate documentation into READMEs for all helm charts within or recursively contained by a directory:
helm-docs
# OR
helm-docs --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.
You can mount a directory with charts under /helm-docs within the container.
Then run:
docker run --rm --volume "$(pwd):/helm-docs" -u $(id -u) jnorwood/helm-docs:latesthelm-docs supports a .helmdocsignore file, exactly like a .gitignore file in which one can specify directories to ignore
when searching for charts. Directories specified need not be charts themselves, so parent directories containing potentially
many charts can be ignored and none of the charts underneath them will be processed. You may also directly reference the
Chart.yaml file for a chart to skip processing for it.
Umbrella Helm chart documentation can include dependency values with document-dependency-values flag.
All dependency values will be merged into values of umbrella chart documentation.
If you want to include dependency values, but don't want to generate doc for each dependency:
chart-search-root parameter to directory that contains umbrella chart and all dependency charts.chart-to-generate flagdocument-dependency-values flag to trueThere are two important parameters to be aware of when running helm-docs. --chart-search-root specifies the directory
under which the tool will recursively search for charts to render documentation for. --template-files specifies the list
of gotemplate files that should be used in rendering the resulting markdown file for each chart found. By default
--chart-search-root=. and --template-files=README.md.gotmpl.
If a template file is specified as a filename only as with the default above, the file is interpreted as being relative to each chart directory found.
If however a template file is specified as a relative path, e.g. the first of --template-files=./_templates.gotmpl --template-files=README.md.gotmpl
then the file is interpreted as being relative to the chart-search-root.
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.valuesTableMd | A table of the chart's values parsed from the values.yaml file (see below) |
| chart.valuesTable | Deprecated. Maps to chart.valuesTableMd |
| chart.valuesSectionMd | A section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no values |
| chart.valuesSection | Deprecated. Maps to chart.valuesSectionMd |
| chart.valueKeyColumnRenderMd | This is a hook template if you want to redefine how helm-docs render the key values. |
| chart.valueTypeColumnRenderMd | This is a hook template if you want to redefine how helm-docs render the type values. |
| chart.valueDefaultColumnRenderMd | This is a hook template if you want to redefine how helm-docs render the default values in chart.valuesSection mode. |
| chart.valueDescriptionColumnRenderMd | This is a hook template if you want to redefine how helm-docs render the description values. |
| chart.valuesTableHtml | Like chart.valuesTableMd but it is rendered as (X)HTML tags to allow further rendering customization, instead of markdown tables format. |
| chart.valuesSectionHtml | Like chart.valuesSectionMd but uses chart.valuesTableHtml |
| chart.valueDefaultColumnRenderHtml | This is a hook template if you want to redefine how helm-docs render the default values in chart.valuesTableHtml mode. This is especially useful when combined with (X)HTML tag |
No open issues yet, or sync has not completed.