stacklok / stacklok/docs-website

Auto-generate Helm values documentation at release time

Open
#957 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation enhancement
Dominant language
TypeScript
Stars
4
Forks
3
Avg merge
1d 7h
Merged PRs (30d)
41

Description

We already have CI scaffolding that pulls generated artifacts at release time and lands them in docs (used for API specs and CRD schemas). The same pattern should work for Helm chart values documentation, but we haven't done it yet.

The main candidate is helm-docs, but two things have blocked it:

  • It's Go-based, which adds a tooling dependency to the docs build that isn't there today.
  • Its output format (Markdown tables of values with descriptions) would need post-processing to fit the site's style and structure.

This matters for the Enterprise configure guides in particular: we're currently maintaining hand-written field tables for the Enterprise Manager, Cloud UI, and Registry Server charts. These will drift. Enterprise also can't be handled by linking to the source repo since the chart is private — generated output checked into docs is the only viable path.

Scope: affects ToolHive OSS charts and Stacklok Enterprise charts. The pipeline approach is the same either way; the Enterprise chart just has the additional constraint of not being publicly linkable.

Starting points worth evaluating:

  • Whether helm-docs output can be massaged in a post-processing step to match the site's style
  • Whether a lighter alternative exists that's not Go-based
  • Whether the existing CRD generation scripts (scripts/extract-crd-schemas.mjs) could be extended or adapted

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the existing release-time artifact pipeline and scripts/extract-crd-schemas.mjs, then evaluate helm-docs and lighter alternatives against the site's documentation style. Compare post-processing needs for ToolHive OSS and Stacklok Enterprise charts; done means a viable pipeline approach is selected for both chart sets, including the Enterprise chart's private-source constraint.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, helm, javascript
Domain
build-system, documentation, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.