Repository navigation
[HWORKS-3351] Split the Helm chart values reference into per-subchart pages (#683) - #686
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.0, adapted to this branch: - The pages follow the 5.0 charts: a brewer page is added (5.0.13 and hopsworks-helm branch-5.0 have that subchart) and the hopsfs-csi page is left out (no 5.0 chart has it). - docs/css/custom.css keeps this branch's stylesheet and appends the values styles. The four design-system tokens they use, which this branch predates, are defined on their two containers with main's light and dark values. The sticky filter bar and anchor offsets clear this branch's sticky navigation tabs from Material's tabs breakpoint up. - scripts/__init__.py registers reset-helm-values only; gen-config-vars is a later main feature. - docs/index.md, which on this branch has no link to the values page, and .claude/docs/design-system.md, which this branch does not have, stay as they are. - scripts/helm_values.py is main's copy after logicalclocks#683; 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:12
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.0: a cherry-pick of 8aa5361, adapted to this branch's older layout.Summary
The 5.0 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.0 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:
brewerpage is added, since 5.0.13 and hopsworks-helmbranch-5.0have that subchart and--strictfails on a key without a page. Thehopsfs-csipage is left out, since no 5.0 chart has that subchart.docs/css/custom.csskeeps this branch's stylesheet and appends the values styles. Those styles use four tokens of the current design system that this branch predates (--hops-accent,--hops-surface,--hops-border,--hops-border-strong). They are defined on the two containers the styles apply to, with main's light and dark values. From Material's tabs breakpoint up, the sticky filter bar and the anchor offsets also clear this branch's sticky navigation tabs.mkdocs.yml: the nav section replaces the single-page entry, andjs/values-filter.jsis added. The other main-only scripts and hooks are not.scripts/__init__.pyregistersreset-helm-valuesonly;gen-config-varsis a later main feature.docs/index.md, which on this branch has no link to the values page (the cloud guides link it by heading id, which the new index keeps), and.claude/docs/design-system.md, which this branch does not have.scripts/helm_values.pyis main's copy after [HWORKS-3351] Split the Helm chart values reference into per-subchart pages #683; the old single page is deleted as on main.The chart side, which rebuilds these docs when a 5.0 patch is published, is logicalclocks/hopsworks-helm#2474.
Test plan
gen-helm-values --strictpasses with 26 pages,brewerincluded, none empty. The Prometheus page keeps its own defaults, with a warning, until hopsworks-helm#2474 ships the tab fix in a 5.0 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.0.hopsworks-docs markdownlintreports 0 issues.🤖 Generated with Claude Code
https://claude.ai/code/session_01RXSgE27b6gGMaS9F7qheRL