Skip to content

Commit 0d5aeb7

Browse files
DOC-6968 Omit a clients-example tab when that client lacks the requested step
Splits the `clients-example` whole-file fallback three ways, so a step a client does not have omits its tab instead of dumping that client's entire file into the pane. 63 panes site-wide were doing that, the worst rendering 258 lines of Go — package declaration, imports and several unrelated examples — where the reader expected a snippet for one command. The condition is three clauses and each is load-bearing: step != "" AND step not in named_steps AND len(named_steps) > 0 Dropping the last would strip every client tab from commands/set.md and commands/get.md, whose files carry no STEP markers at all, so for them the whole file genuinely is the example. Dropping the first would break the deliberate step="" usage on data-store.md. Both verified untouched. `named_steps` is always present in examples.json and is `{}` rather than null when a file has no steps, which is what makes the length test safe — checked across all 433 distinct step names. Membership in named_steps is tested rather than $sliceable on purpose. A step that exists but whose line range is malformed or out of bounds should still fall through to the whole-file path, because absorbing that drift is exactly what the $sliceable guard was written for; conflating the two would turn a data problem into a silently missing tab. Using `isset` with the step as a variable also survives the two step names that contain dots (`ltrim.1`, `rule_1.1`) — dots only break the `.field` access form, and lists.md renders byte-identically across this change. The `continue` fires before any content is built, not merely before the tab is appended. The legacy path mutates .Page.Store and inlines the file once per page, so building it for a tab we then drop would leave orphaned markup and a wasted copy of the file in the output. Each omission emits a warnf naming page, client, step and set. Review flagged the resulting 63 new build warnings as unwelcome noise and approved on the understanding they are temporary — the follow-up work that clears them is the next change, and they must be fixed rather than silenced. They are self-extinguishing by construction: the count is exactly the number of missing examples. CI runs plain `hugo -d output` with no --panicOnWarning and the build still exits 0. Verified before and after on identical trees: 2711 panes -> 2648, legacy panes 100 -> 37, and the 63 warnings correspond one-to-one with the 63 removed panes. What remains on the legacy path is exactly the two protected classes, 25 cosmetic panes plus 12 from step="". All 594 tab groups keep at least one pane so nothing renders empty; selector options still match panes on the worst-hit group; and the .md and .json outputs stayed consistent for free, because code-examples-json.html derives its language list by scraping the rendered panels rather than recomputing it. Learned: data/examples.json is gitignored build output, so it must be regenerated after any branch switch before rendering is measured, or the measurement silently describes the tree you were on before Constraint: keep all three clauses of the omit condition — dropping the len(named_steps) > 0 test strips every client tab from commands/set.md and commands/get.md, which have no STEP markers at all Constraint: the continue must fire before content is built, because the legacy path mutates .Page.Store and inlines the whole file once per page Rejected: gating omission on $sliceable rather than named_steps membership | a step whose range is malformed should still fall back to the whole file, which is what that guard exists for Directive: the omission warnings are a worklist, not noise — fix the missing examples rather than silencing the warnf, which was the condition on which review accepted them Directive: do not add a whole-file last resort for groups that lose every client tab — vector3/vector4 intentionally degrade to CLI-only, and a single-pane group is an existing shape elsewhere on the site Gaps: scan.md still loses 7 of its 12 client tabs and the h* pages 2 each until the cmds_generic and cmds_hash steps are written; the warnf output is the worklist and the next change addresses it Ticket: DOC-6968 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 0f2cfea commit 0d5aeb7

1 file changed

Lines changed: 29 additions & 0 deletions

File tree

layouts/partials/tabbed-clients-example.html

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,35 @@
140140
{{ end }}
141141
{{ end }}
142142

143+
{{/* A step was requested that this client's file does not contain. Three cases hide
144+
behind that, and only the middle one is a defect:
145+
146+
step="" (explicitly empty) -> the whole file IS the example. Keep it.
147+
file has other steps, not this one -> an AUTHORING GAP. Omit the tab: the
148+
legacy path below would otherwise dump the client's entire file — imports,
149+
connection setup and every unrelated example — into a pane the reader
150+
opened for one command. Up to 258 lines where a snippet belongs.
151+
file has NO steps at all -> predates STEP markers, so the whole file is
152+
still the closest thing to an example. Keep it, or pages like
153+
commands/set.md and commands/get.md lose every client tab.
154+
155+
The len > 0 clause is what separates the last two, and it is load-bearing.
156+
Note this tests membership in named_steps rather than $sliceable: a step that
157+
exists but whose range is malformed or out of bounds should still fall through
158+
to the whole-file path, which is the safety net that guard was written for. */}}
159+
{{ $omitTab := false }}
160+
{{ if and (ne $step "") (isset $example "named_steps") }}
161+
{{ $steps := index $example "named_steps" }}
162+
{{ if and (gt (len $steps) 0) (not (isset $steps $step)) }}
163+
{{ $omitTab = true }}
164+
{{ warnf "[tabbed-clients-example] %q: client %q has no step %q in set %q — tab omitted. Add the step to that client's example file, or name the supporting clients in lang_filter." $.Page $client $step $id }}
165+
{{ end }}
166+
{{ end }}
167+
{{/* Skip before any content is built: the legacy path mutates .Page.Store and inlines
168+
the whole file once per page, so building it for a tab we then drop would leave
169+
orphaned markup behind. */}}
170+
{{ if $omitTab }}{{ continue }}{{ end }}
171+
143172
{{ $content := "" }}
144173
{{ $fullFileKey := "" }}
145174
{{ $hlRange := "" }}

0 commit comments

Comments
 (0)