Commit 0d5aeb7
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
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
140 | 140 | | |
141 | 141 | | |
142 | 142 | | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
143 | 172 | | |
144 | 173 | | |
145 | 174 | | |
| |||
0 commit comments