docs(opentelemetry-collector): generate values documentation with helm-docs

[marcschaeferger]

Description

Adds generated values documentation for the opentelemetry-collector chart using helm-docs as the first scoped implementation of #430.

The existing hand-written README content is preserved through README.md.gotmpl, while the values table is generated from annotations in values.yaml. helm-docs is integrated with the existing pre-commit setup so generated documentation is checked for drift in CI.

This PR is intentionally limited to the Collector chart based on @TylerHelmuth feedback/request to start with one chart. The remaining charts stay excluded through .helmdocsignore and will be migrated separately after this approach has been reviewed.

The chart version is bumped from 0.171.0 to 0.171.1, and the Collector examples are regenerated accordingly. The generated documentation, example checks, Helm lint, and the full pre-commit suite were verified locally.

Link to tracking issue

Part of #430

Authorship

• I, a human, wrote this pull request description myself.

[TylerHelmuth]

The precommit stuff was an attempt to enforce example generation but we never really finished it. Lets not require it here.

[marcschaeferger]

Makes sense. I'm fine with not making the existing pre-commit setup a requirement if that part of the repository was never fully completed.

My main concern is not pre-commit itself, but preventing drift between the source files, primarily values.yaml and README.md.gotmpl and the generated README.md.

For example, if a value is added, renamed, deprecated, or its default value or description changes, the committed Values table can otherwise become stale without anyone noticing. The README would still look perfectly valid, but its documented configuration would no longer accurately represent values.yaml.

The same applies to changes in the README template itself: since the final README is generated from both the template and the chart metadata,

---

So I see two reasonable approaches:

1. use pre-commit for fast local feedback, or
2. keep local generation optional and enforce the generated state in CI.

I'm completely fine with the second option here, what ever you guys as Maintainers prefere.

A small CI check could simply run helm-docs and fail if generation produces a diff, for example with git diff --exit-code.

That would also line up with your original suggestion in #430 to add something to the workflow that ensures the generated documentation stays in sync:

#430 (comment)

There are already several established projects using this general pattern, for example:

• Grafana Helm Charts runs helm-docs as part of its CI validation:
  https://github.com/grafana/helm-charts/blob/main/.github/workflows/linter.yml
• Argo Helm includes generated Helm documentation in its lint/test workflow:
  https://github.com/argoproj/argo-helm/blob/main/.github/workflows/lint-and-test.yml
• and more

Refs/Docs:

• OneUptime also documents both CI/CD drift detection and pre-commit integration as approaches for helm-docs:
  https://oneuptime.com/blog/post/2026-02-09-helm-docs-documentation-generation/view#automating-documentation-in-ci-cd

These are only a few examples; usage is not limited to CNCF projects either. I can collect more concrete downstream examples if that would be useful.

---

There is also another benefit we could consider separately in the future: using the same values.yaml metadata to keep both the documentation and values.schema.json synchronized.

That's the approach I currently use for several Company, OSS and Private Helm charts. The workflow generates:

• README.md via helm-docs
• values.schema.json via losisin/helm-values-schema-json

and then CI verifies the generated artifacts. helm-values-schema-json can explicitly reuse descriptions written in the helm-docs comment format, so the same annotations in values.yaml can serve as the source for both human-readable documentation and machine-readable schema validation.

For reference:

• https://github.com/losisin
• https://github.com/losisin/helm-docs-github-action
• https://github.com/losisin/helm-values-schema-json

So if you prefer, I can remove the pre-commit integration from this PR and replace it with a small CI-only drift check. That keeps this independent of the unfinished pre-commit setup while still ensuring the generated documentation cannot silently get out of sync.

[TylerHelmuth]

It looks like this is technically a retired project. Did anyone fork it and continue maintaining? Do you know what other popular helm charts are using?

[marcschaeferger]

Ok, I looked into the maintenance status more closely, and I agree that helm-docs looks somewhat stale at first glance.

The latest tagged release is still v1.14.2 from July 2024, so the lack of releases is definitely a valid concern.

However, the repository itself has not been completely inactive. There were multiple maintenance and dependency updates merged in 2026; they simply haven't resulted in a new tagged release yet.

There was also an issue specifically asking whether the project was still alive:

norwoodj/helm-docs#301

A maintainer explained there that the project had been on a break because of limited time, that they were looking for additional people to help with issue triage and PR reviews, and that they had started looking into recent PRs and updating dependencies again.

There were also community members volunteering to help maintain the project, with the maintainer responding that they wanted to coordinate that effort.

So I wouldn't describe it as completely abandoned. I do agree though, that the current release and maintenance situation deserves some caution.

At the same time, helm-docs is still actively consumed by quite a few major CNCF projects, including:

• Argo Helm
• Cilium
• Crossplane
• KEDA
• External Secrets

and there is many additional users outside CNCF projects as well.

Grafana, for example, is still using generated documentation for charts such as rollout-operator, and projects such as Grafana and Argo also include generated-documentation verification in CI.

There is also actively maintained tooling around helm-docs. In particular, losisin maintains several useful projects:

• https://github.com/losisin
• https://github.com/losisin/helm-docs-github-action
• https://github.com/losisin/helm-values-schema-json

helm-docs-github-action wraps helm-docs for GitHub Actions and supports fail-on-diff, version selection, and optional automatic commits.

helm-values-schema-json is particularly interesting because it generates values.schema.json and can reuse descriptions from the helm-docs comment format. This means the same metadata in values.yaml can be used for both the generated README and the Helm values schema.

That's also the approach I currently use for almost all chart i'm responsible (Work/OSS/Private) charts: helm-docs generates the README, helm-values-schema-json generates the schema, and CI checks the generated artifacts.

There are alternatives as well. For example, Bitnami/Broadcom maintains:

https://github.com/bitnami/readme-generator-for-helm

It can generate both README parameter documentation and an OpenAPI-compatible values schema, and it currently has a more active release cadence.

Technically, that's certainly an alternative worth mentioning. Personally, though, I would strongly prefer not to introduce Bitnami/Broadcom dependency here. I've worked closely with Broadcom-related products at work and with Bitnami tooling for a long time in my day-to-day work as Senior/Teamlead DevSecOps, including dealing with the operational impact of their recent image/policy changes, so based on that experience it would not be my prefered direction and i would rather jump off a cliff.

I also haven't found a fork of norwoodj/helm-docs that has clearly established itself as the community-maintained successor.

I'll reach out to the helm-docs maintainers directly and ask about the current maintenance and release plans. If additional help is useful, I'd also be open to contributing there — I already help maintain and contribute to several other open-source projects.

Depending on their response and the longer-term state of the project, there are several possible paths in my view:

• continue using a pinned helm-docs release with CI drift checks;
• (me and others) contribute upstream and help improve its maintenance/release situation;
• use or help maintain an appropriate community fork if one emerges;
• or, if necessary, I can make tooling I've already build around this use case publicly available.

I definitely don't want to introduce a dependency here that becomes a maintenance problem for OpenTelemetry. At the same time, given the amount of continued downstream usage, the recent upstream maintenance activity, and the surrounding ecosystem, I don't think the lack of a recent tagged release alone necessarily makes helm-docs unusable.