Skip to main content

Research: Helm Chart Documentation Generator

R1: OCI Registry Version Lookup​

Decision: Use helm show chart oci://ghcr.io/cnoe-io/charts/ai-platform-engineering | yq '.version' to get the latest published version.

Rationale: The helm show chart command fetches the latest tag from the OCI registry without downloading the full chart. Combined with yq for YAML parsing, this gives us the published version field. Since published releases don't contain RC suffixes, this directly satisfies FR-007. If the command fails (no network, no auth), we fall back to the local appVersion from Chart.yaml.

Alternatives considered:

  • crane ls / skopeo list-tags: Requires additional tools not universally available; would need tag filtering logic
  • GitHub API (gh api): Would need authentication and rate limiting; more fragile
  • Hardcoded version file: Requires manual maintenance; defeats the purpose of automation

R2: Values Table Generation Strategy​

Decision: Run helm-docs first to regenerate the raw README.md with values tables from values.yaml comments, then post-process the output to add enrichment sections.

Rationale: The project already has make helm-docs which runs helm-docs --chart-search-root charts/. This produces accurate values tables directly from values.yaml with proper column formatting. Our script wraps this existing tool and enriches the output rather than reimplementing values parsing.

Alternatives considered:

  • Parse values.yaml directly with yq: Would lose the description comments that helm-docs extracts; more code, more bugs
  • Use a custom Python script: Adds a Python dependency for a task that helm-docs already handles perfectly
  • Keep helm-docs output unchanged and only generate Docusaurus pages: Source READMEs would lack usage examples

R3: Script Language Choice​

Decision: Bash with yq for YAML parsing.

Rationale: The Makefile already uses Bash for all targets. yq (v4+) handles YAML parsing safely without the risks of grep/sed on structured data. Both helm-docs and yq are standard DevOps tools. No new language runtime required.

Alternatives considered:

  • Python: Would add a dependency; overkill for file templating
  • Node.js: Already used for Docusaurus but adding a Node script for Helm docs creates an odd coupling
  • sed/awk for YAML: Fragile, error-prone for structured data

R4: MDX Escaping Strategy​

Decision: Replace <URL> patterns with [URL](URL) markdown links; escape angle brackets in non-link contexts with \< and \>.

Rationale: Docusaurus uses MDX which interprets <...> as JSX components. The most common offender is helm-docs output containing <https://...> source URLs. Converting to standard markdown links is semantically correct. For other angle brackets (e.g., in value descriptions like <release>-<service>), they're typically inside backtick code spans which MDX handles safely.

Alternatives considered:

  • Use .mdx extension with explicit escaping everywhere: More work, no benefit over .md
  • Strip all HTML-like content: Would lose legitimate formatting

R5: Auto-Generated Marker Format​

Decision: Use an HTML comment at the top for machine detection plus a visible admonition for human readers.

Rationale: The HTML comment (<!-- AUTO-GENERATED ... -->) allows scripts to detect and verify the marker. The visible admonition warns human editors. Both are preserved across helm-docs regeneration since they appear above the helm-docs template markers.

Format for source README:

<!-- AUTO-GENERATED by scripts/generate-helm-chart-docs.sh — DO NOT EDIT -->
<!-- Source: charts/<path>/Chart.yaml, charts/<path>/values.yaml -->
<!-- Regenerate: make docs-helm-charts -->

Format for Docusaurus page (after frontmatter):

:::caution[Auto-generated]
This page is auto-generated from the Helm chart source. Do not edit directly.
Regenerate with `make docs-helm-charts`.
:::

R6: Version Stripping for Dependencies​

Decision: Strip -rc.* suffixes using sed 's/-rc\.[^"]*//g' when rendering dependency version columns. For external dependencies (versions not matching the project's RC pattern), display as-is.

Rationale: Internal subchart versions follow the pattern X.Y.Z-rc.helm.N. Stripping everything after -rc gives the clean base version. External deps like neo4j (2025.07.1) or milvus (5.0.2) don't have -rc suffixes and pass through unchanged.