helm-docs

helm-docs

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.

Installation

helm-docs can be installed using homebrew:

brew install norwoodj/tap/helm-docs

or scoop:

scoop install helm-docs

or mise:

mise use -g helm-docs@latest

This will download and install the latest release of the tool.

To build from source in this repository:

cd cmd/helm-docs
go build

Or install from source:

go install github.com/norwoodj/helm-docs/cmd/helm-docs@latest

Usage

Pre-commit hook

If 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-hooks

Future 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

To pin the 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

Running the binary directly

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 READMEs

The tool searches recursively through subdirectories of the current directory for Chart.yaml files and generates documentation for every chart that it finds.

Using docker

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:latest

Ignoring Chart Directories

helm-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.

Generating Doc with Dependency values

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:

• set chart-search-root parameter to directory that contains umbrella chart and all dependency charts.
• list all charts you want to generate doc using chart-to-generate flag
• set document-dependency-values flag to true

Markdown Rendering

There 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