✨ Add a steps component#293
Open
chrisjsewell wants to merge 3 commits into
Open
Conversation
Add a `steps` container and `step` item directive for numbered, visually-connected procedures (install guides, tutorials), a commonly hand-rolled CSS snippet. The doctree is a real ordered list (`enumerated_list` of `list_item`), so the numbering is semantic: assistive technology announces the step count/position and non-HTML builders degrade to a plain numbered list. The visible circular markers and connecting rail are drawn purely with CSS in `style/steps.css`; the marker number is `counter(list-item)`, the built-in list counter, so it honours the `<ol start="N">` offset with no number baked into the doctree — translations and re-ordering can never desynchronise it. No JavaScript is involved. `steps` takes `start` (offset), `color` (semantic marker colour) and `class`; `step` takes an optional title (a `rubric`, as for tab labels) plus `class`/`class-title`/`class-content`. A `step` outside `steps`, or a non-`step` child of `steps`, warns (`design.steps`), mirroring tabs. The `.sd-steps-<colour>` marker variants are generated data-driven from the palette in `style/design.toml` (new `gen_steps` family, registered in the `ASSEMBLY` cascade after `steps.css`); the structural count test is extended accordingly. Markers/rail take their colour from the semantic palette so themes retint them automatically, and use logical properties for RTL.
Address review of the `steps` component:
- B1 (double numbering): Sphinx's `basic.css` sets `ol.arabic {list-style:
decimal}` at specificity (0,1,1), which beat the plain `.sd-steps`
(0,1,0) rule, so the native "N." marker rendered beside the circular
one on every theme (basic.css ships with all of them). Raise the reset
to `.sd-steps.sd-steps {list-style: none}` (0,2,0) so it wins
independent of stylesheet load order. Regenerated the artifact.
Verified in Chromium: computed `list-style-type` is `none` under both
alabaster and furo.
- M2 (dropped targets): keep `nodes.target` children of `steps`, matching
the tab-set policy — a target renders fine and docutils PropagateTargets
relocates its id onto the following step, so `:ref:` still resolves.
- m3 (list semantics): removing the native marker makes WebKit/VoiceOver
drop the list role, so `steps` now emits a `steps_list` node whose HTML
visitor delegates to the writer's `visit_enumerated_list` and injects
`role="list"`; non-HTML builders render it as a plain enumerated_list.
Verified role="list" in HTML and unchanged text/LaTeX numbered output.
Tests added for the target reference, the list role and the non-HTML
degradation; doctree fixtures updated for the new node type.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #293 +/- ##
==========================================
+ Coverage 92.63% 92.94% +0.31%
==========================================
Files 13 14 +1
Lines 1371 1446 +75
==========================================
+ Hits 1270 1344 +74
- Misses 101 102 +1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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
1 participant
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.
Adds
steps/stepdirectives for numbered procedures (install guides, tutorials) — one of the most-copied custom CSS snippets across Sphinx sites, now built in. CSS-only: circular markers and a connecting rail viacounter(list-item), no JavaScript, no numbers baked into the doctree.Design
enumerated_list/list_itemsubclassed assteps_list): assistive tech announces position and count, translations and reordering can never desync the numbering, and LaTeX/text/man degrade to genuine numbered lists honouring:start:(all built and verified; gettext extracts each step title exactly once).:start:maps to native<ol start>— the CSScounter(list-item)follows it by definition;:color:selects from the palette via a generated utility family (data-driven; one rule perdesign.tomlcolour, locked by the structural count test).role="list"is emitted on the HTML<ol>(delegating visitor patching the writer's own output, sostart/enumtypehandling stays version-proof) — WebKit/VoiceOver drop list semantics onlist-style: noneotherwise.list-stylereset uses a doubled-class selector to out-rank Sphinxbasic.css'sol.arabicrule — review caught the double-numbering this caused on every theme, verified fixed by computed-style probes under alabaster and furo.:ref:resolves (review caught the silent drop; now tested).stepchildren and orphansteps warn (design.steps, suppressible).Verification
role="list",startfidelity, correct marker positioning nested inside cards/grids/dropdowns-nW; artifact regenerated through the generator pipeline with the count test extended for the new family