Repository navigation
[HWORKS-3351] Split the Helm chart values reference into per-subchart pages (#683) - #685
Merged
Merged
Conversation
… pages (logicalclocks#683) * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 The Helm chart values reference is one 2890-row table copied from the chart README. Its long JSON defaults push the table far past the content column, the charts Hopsworks installs from upstream are documented only as those defaults, and the RonDB chart docs at docs.hopsworks.ai/rondb-helm/ are not versioned. hopsworks-helm#2469 (HWORKS-3342) also stops embedding the subchart values in the root README the reference is built from. The docs build now generates one page per top-level values key into committed stub pages listed in the nav, from the same chart package as before. Rows come from the root README and every subchart README, keyed from the root, and the first row of a key wins, so charts rendered with and without helm-docs -u produce the same pages. On today's charts this also drops the two kserve keys that -u lists twice. Each value is a definition-list entry, because a key chip in a table cell never wraps and keys run to 90 characters. Long defaults are collapsed YAML, and each section carries its defaults as a values file. Subchart pages state their deployment condition and link the upstream charts at the version the chart pins. The RonDB page renders the values.schema.json of the pinned RonDB chart instead of linking the unversioned page. The index lists the values the cloud setup guides set. Every key has an anchor, deprecated values are labelled, and long pages get a filter box; without JavaScript every entry stays visible. A values row that does not parse fails the build instead of being dropped. The PR check runs the generator with --strict, which also fails on a top-level key without a page, an upstream chart repository without a docs link, a missing common value or a missing RonDB schema. The deploy workflow only warns. The page URL is unchanged: helm_chart_values.md and helm_chart_values/index.md serve the same path. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Link the values reference from the home page by its heading ID instead of its file path, as the content guide asks for links between pages. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Mute a deprecated value's description with the theme's light foreground instead of 60% opacity, which put it at 4.12:1 in dark mode and 4.30:1 in light mode, below WCAG AA. It now measures 4.90:1 and 4.59:1; the key, code chips and links keep their normal colours. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Wrap bare URLs in value descriptions as Markdown autolinks. The site has no magiclink extension, so a bare URL rendered as text that could not be clicked; 13 URLs in 10 descriptions (RonDB schema and chart values) are affected. Code spans and existing links are left alone, and trailing punctuation stays outside the link. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Render every parsed default as YAML, scalars included. Six long string defaults were shown as raw text, and some read as lists or maps (jupyter_shell_command shows as ["/bin/bash", ...]); quoted YAML keeps them strings when copied into a values file. Prose defaults stay text. In a local checkout, read the RonDB schema from the archive of the pinned version instead of the first rondb-*.tgz, so a stale archive left next to it cannot be rendered under the new version's link. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Fail the PR check when generated Helm values content is committed. The pages are filled at build time, and a committed copy is published as-is whenever a build leaves a page alone, for example a docs branch cut before its chart is in Nexus, which would show another version's values under that version's label. Add hopsworks-docs reset-helm-values, which puts each page's placeholder back between the generation markers and keeps everything else. The check runs it and fails if it changed a committed page, printing the two commands that fix the branch; the README uses it in place of a git checkout after a local preview. The committed pages are written in the reset's own format, so a reset of a clean branch changes nothing. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Show what Hopsworks deploys on the RonDB page. The RonDB chart values were listed with that chart's own defaults, although Hopsworks overrides 32 of them, for example maxNumMySQLServers (the RonDB chart says 5, Hopsworks deploys 1) and the image registry. The overrides of the wrapper subchart's values.yaml and then the root values.yaml are now merged over the schema defaults the way Helm merges them: maps merge, lists replace and null unsets. An overridden entry names the RonDB chart's own default. For the 5.1.0 chart all 300 entries with a default match the values Helm computes for the RonDB subchart. An override of a key the RonDB schema does not declare, usually a value RonDB renamed that the override then stops setting, is reported and fails the PR check with --strict. The RonDB entries also show the schema's minimum, maximum, pattern and first example. The schema's required is left out: the defaults fill those keys, so it would read as a value the user has to set. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Show what Hopsworks deploys on every subchart page, not only RonDB. A subchart's rows carry that subchart's own defaults, while the root values.yaml overrides some of them inside a collapsed map, so the page showed the wrong value: hopsfs.datanode.count 1 where Hopsworks deploys 5, the admin JVM heap 2048 instead of 4096, the MinIO limits. The root settings for each subchart are now merged over its own defaults with Helm's rules, and the row shows the result; both layers are Hopsworks', so no second default is named. Checked with helm template on the 5.1.0 package, with a throwaway template printing each enabled subchart's .Values (20 subcharts, 2207 defaults): the merge fixes the 9 rows that differed. The 32 left are by design: the hopsworkslib slot and upstream chart subtrees, to which Helm adds the library's and upstream chart's own values, the command-line Velero flag of the check, and one int64 that Helm turns into a float. charts/prometheus/values.yaml has a tab character PyYAML rejects (Helm's parser accepts it); that page keeps its own defaults and the generator prints a warning. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Keep a parent's whole default in the "Defaults as YAML" blocks. A key with a listed child was left out entirely, so its other keys vanished from the block: 84 keys under 17 parents on main, among them the whole Hopsworks Grafana configuration under grafana.grafana, the admin probe timings, kafka.cluster.zookeeper.replicas and most of spark.historyServer. Parents are now set first and listed children over them; a scalar or null parent default gives way to a listed child. Checked on main: all 2879 listed defaults read back from their subchart's block at their path, 25 of them object defaults (the root chart's partial map for each subchart) that their children fill in. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Say on each subchart page which upstream chart values it lists. The "Upstream charts" box named and linked each chart, but only the index said that a page lists just the values Hopsworks sets for it, so a reader landing on grafana.md could take the grafana.grafana default for every setting there is. The box now says so under the links, and for RonDB, whose chart values the page renders in full, it links that section instead. The entry of the key a chart is configured under (grafana.grafana, trino.trinotest, rondb.rondb) carries the same link, for a reader who arrives from its anchor. The index intro drops "third-party", since RonDB is not, and says a default is what Hopsworks deploys. Generated notes no longer go through the bracket escaping meant for helm-docs descriptions, which would break the in-page RonDB link; the other notes are code spans. "Defaults as YAML" is dumped with sorted keys again. Setting parents before children made the insertion order follow key depth, so grafana.grafana came before grafana.dependencies. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Fail --strict when two entries on a page share an anchor. The RonDB wrapper README documents rondb.rondb as one object row because of the helm-docs comment on that key; a helm-docs comment on any key under it would add a README row the rendered schema also lists, and the page would carry the value twice under one id, with fragment links landing on whichever comes first. Keys whose anchors differ only in characters the anchor replaces collide the same way. The check names the page, the anchor and the keys, and leaves the choice between the two descriptions to whoever adds the comment. No page has a shared anchor for main or 5.1.0; a 5.1.0 copy with one README row under rondb.rondb fails the step. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * [HWORKS-3351] Split the Helm chart values reference into per-subchart pages https://hopsworks.atlassian.net/browse/HWORKS-3351 Fail --strict when a Hopsworks override sets a key to null while values under it are listed. Helm removes such a key with everything below it, but the merge keeps the null as a value, so the entries under it would go on showing their chart defaults and "Defaults as YAML" would rebuild the removed subtree. The check covers the root chart's settings for each subchart and the RonDB overrides merged over its schema, and names the key. main and 5.1.0 have 19 null overrides each, all on leaves, and pass. A 5.1.0 copy with hopsfs.datanode and rondb.rondb.clusterSize set to null fails with both keys named. Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Backport to branch-5.1: the hopsfs-csi page and its nav entry are left out, since no 5.1 chart has that subchart (5.1.0 in Nexus and hopsworks-helm branch-5.1). scripts/helm_values.py is main's copy after logicalclocks#683, which also brings the subchart README reading of logicalclocks#682 that this branch did not have; the old single page is deleted as on main. --------- Signed-off-by: Mahmoud Ismail <mahmoud@logicalclocks.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> (cherry picked from commit 8aa5361)
maismail
marked this pull request as ready for review
October 6, 2026 14:13
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://hopsworks.atlassian.net/browse/HWORKS-3351
Backport of #683 to
branch-5.1: a cherry-pick of 8aa5361.Summary
The 5.1 docs get the per-subchart Helm chart values reference from #683. It is an index plus one page per top-level values key, generated at build time from the newest 5.1 chart in Nexus and never committed. The PR check runs the generator with
--strictand checks that the pages hold only their placeholders.Adapted to this branch:
hopsfs-csipage: no 5.1 chart has that subchart (5.1.0 in Nexus, hopsworks-helmbranch-5.1), so the page would stay empty.scripts/helm_values.pyis main's copy after [HWORKS-3351] Split the Helm chart values reference into per-subchart pages #683. It also brings the subchart README reading of [HWORKS-3342] Trim the Helm release secret back under the size gate #682, which this branch did not have. The generator and the old single page, which is deleted as on main, were the only conflicts.The chart side, which rebuilds these docs when a 5.1 patch is published, is logicalclocks/hopsworks-helm#2473.
Test plan
gen-helm-values --strictpasses with 25 pages, none empty. The Prometheus page keeps its own defaults, with a warning, until hopsworks-helm#2473 ships the tab fix in a 5.1 patch.hopsworks-docs check(strict mkdocs build) passes with the generated pages. Locally the API section was built from hopsworks-api main; CI builds it frombranch-5.1.hopsworks-docs markdownlintreports 0 issues.mkdocs.yml(this branch's own nav entries) and the droppedhopsfs-csipage.🤖 Generated with Claude Code
https://claude.ai/code/session_01RXSgE27b6gGMaS9F7qheRL