jnorwood/helm-docs

helm-docs

概述

helm-docs是一个从Helm图表自动生成Markdown文档的工具。生成的文档包含图表元数据以及所有图表值的表格，包括默认值和从注释中解析的可选描述。文档生成完全由https://golang.org/pkg/text/template驱动，工具会解析图表元数据并生成多个子模板，可在模板文件（默认`README.md.gotmpl`）中引用。若未提供模板文件，工具将使用默认内部模板生成格式合理的README。

核心功能和特性

• 自动文档生成：从Helm图表的Chart.yaml和values.yaml提取信息，生成结构化Markdown文档
• 模板驱动：基于Go模板系统，支持自定义模板文件（默认README.md.gotmpl）
• values.yaml解析：从注释中提取值描述，自动生成包含键、类型、默认值和描述的表格
• 忽略机制：支持.helmdocsignore文件，用于排除不需要处理的图表目录
• 预提交集成：可配置为pre-commit钩子，在提交时自动更新文档
• Sprig模板库：内置https://github.com/Masterminds/sprig，支持丰富的模板函数

使用场景和适用范围

• Helm图表开发过程中文档的自动化生成与维护
• 确保图表文档与values.yaml配置保持同步
• 团队协作中保持图表文档格式一致性
• CI/CD流程中集成文档自动更新

安装方法

使用Homebrew安装

bash
brew install norwoodj/tap/helm-docs

此命令将下载并安装工具的https://github.com/norwoodj/helm-docs/releases/latest。

从源码构建

bash
cd cmd/helm-docs
go build

使用方法

基本用法

在目录中或递归地为所有Helm图表生成文档并输出到README：

bash
helm-docs
# 或
helm-docs --dry-run  # 将生成的文档打印到stdout而非修改README

工具会递归搜索当前目录的子目录中的Chart.yaml文件，并为找到的每个图表生成文档。

可用模板

工具生成的模板如下，可在README.md.gotmpl文件中通过{{ template "template-name" . }}引用：

默认模板

若不存在README.md.gotmpl（或其他指定的模板文件），将使用默认模板生成README：

{{ template "chart.header" . }}
{{ template "chart.description" . }}

{{ template "chart.versionLine" . }}

{{ template "chart.sourceLinkLine" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}

忽略图表目录

helm-docs支持.helmdocsignore文件（类似.gitignore），可指定搜索图表时要忽略的目录。被指定的目录无需是图表本身，因此包含多个图表的父目录可被忽略，其下所有图表均不处理。也可直接引用Chart.yaml文件以跳过特定图表。

values.yaml元数据解析

工具可从values.yaml文件解析值的描述和默认值。默认值直接从YAML中提取，描述可通过特定格式的注释添加。

基本注释格式

在文件中通过以下格式的注释为参数添加描述：

yaml
controller:
  publishService:
    # controller.publishService.enabled -- 是否将ingress控制器暴露给公网
    enabled: false

  # controller.replicas -- 负载均衡的nginx-ingress pod数量。
  # 不要设置为小于2的值。
  replicas: 2

注释可跨多行，后续行无需双破折号，将自动以空格连接。

值表生成规则

• 默认仅添加叶节点（类型为int、string、float、bool、空列表和空映射的字段）到值表，即使它们没有描述注释
• 包含元素的列表和映射不会自动添加到值表，除非它们有对应的描述注释
• 为非空列表/映射添加描述注释后，其下的叶节点不会自动添加到值表。若需同时记录非空列表/映射及其下的叶节点，需为两者都添加描述注释

示例：

yaml
controller:
  # controller.livenessProbe -- 配置ingress控制器的健康检查
  livenessProbe:
    httpGet:
      # controller.livenessProbe.httpGet.path -- 健康检查端点
      path: /healthz
      port: http

生成的值表：

若移除controller.livenessProbe的注释：

yaml
controller:
  livenessProbe:
    httpGet:
      # controller.livenessProbe.httpGet.path -- 健康检查端点
      path: /healthz
      port: http

生成的值表：

nil值处理

若需定义键但保留默认值为空，可指定描述和类型：

yaml
controller:
  # controller.replicas -- (int) 负载均衡的nginx-ingress pod数量
  replicas:

自定义默认值列

若不想使用values.yaml中的默认值，或实际默认值在图表内部计算，可通过@default注释修改默认值列：

yaml
service:
  # service.annotations -- 为服务添加注释
  # @default -- 图表将自动添加一些内部注释
  annotations: []

注意：键的注释必须在第一行，@default注释需紧随其后。

含特殊字符的键

若键名包含.或空格，注释中需将该部分用引号括起：

yaml
service:
  annotations:
    # service.annotations."external-dns.alpha.kubernetes.io/hostname" -- 分配给服务ELB的主机名
    external-dns.alpha.kubernetes.io/hostname: stupidchess.jmn23.com

configMap:
  # configMap."not real config param" -- 示例用的假配置参数
  not real config param: value

Pre-commit钩子

若要通过pre-commit钩子自动生成README.md文件，需先安装pre-commit二进制文件，并在项目中添加https://github.com/norwoodj/helm-docs/blob/master/.pre-commit-config.yaml，然后运行：

bash
pre-commit install
pre-commit install-hooks

之后，对图表的requirements.yaml、values.yaml或Chart.yaml文件的修改将在提交时触发文档更新。