Repository navigation
Improve layout and styling of need cards - #13
Merged
Merged
Conversation
sphinx-needs shows every incoming link of a need. On the Zephyr requirements document one requirement has 434 "covered by" links to test results, and one test case of the test specification has 67 "has results" links. The lists hide the rest of the need. need_layouts.need_layout(hide_backlinks=[...]) gives the sphinx-needs "clean" layout without the incoming side of the named links. links_line(hide_backlinks) gives the links line alone, for a document's own layout in place of <<meta_links_all()>>. zdocs_conf re-exports both for conf.py. The engine writes the exclude list itself: no layout string is parsed or changed. A name that is no link name (a space, a quote) is an error. The links stay in the need data, so needs.json, need tables and need flows still have them. On the Zephyr build, hiding covers and assesses on requirements and result_of on test cases takes the logging requirements page from 606 KB to 102 KB and the logging test-spec page from 323 KB to 86 KB. "verified by" and the other links stay. Unit 414 (+11), acceptance 321/321, zdocs docs 0 warnings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
There was a problem hiding this comment.
🟡 Changes recommended
Windows path handling, invalid color validation, and keyboard focus ordering introduce concrete regressions.
3 open findings
What changed in this PR
This PR adds styled need cards while reorganizing shared Sphinx support modules and their test fixtures.
Changes:
- Adds configurable card layouts, type colors, status styling, and accessibility-related presentation.
- Enhances adequacy reports and generated reference sections.
- Moves shared modules and fixtures into dedicated directories and updates test configuration.
| File | Description |
|---|---|
sphinx/zdocs_conf.py |
Loads card support and CSS. |
sphinx/requirements-doc.txt |
Updates module path documentation. |
sphinx/_static/zdocs-needs.css |
Defines need-card styling. |
sphinx/_scripts/twister_reader.py |
Moves and extends Twister parsing. |
sphinx/_scripts/rst_builders.py |
Groups generated references. |
sphinx/_scripts/needs_fields.py |
Handles optional need fields. |
sphinx/_scripts/need_layouts.py |
Provides card layout helpers. |
sphinx/_scripts/doxygen_parser.py |
Moves Doxygen parsing support. |
sphinx/_scripts/adequacy.py |
Adds need-title extraction. |
sphinx/_scripts/_tests/test_twister_reader.py |
Updates Twister test fixtures. |
sphinx/_scripts/_tests/test_rst_builders.py |
Tests reference containers. |
sphinx/_scripts/_tests/test_need_layouts.py |
Tests card layouts. |
sphinx/_scripts/_tests/test_doxygen_parser.py |
Updates parser fixtures. |
sphinx/_scripts/_tests/roots/test-needlayouts/index.rst |
Adds layout test needs. |
sphinx/_scripts/_tests/roots/test-needlayouts/conf.py |
Configures layout test project. |
sphinx/_scripts/_tests/conftest.py |
Configures script tests. |
sphinx/_scripts/_tests/.gitignore |
Ignores test artifacts. |
sphinx/_fixtures/twister/twister.json |
Adds Twister fixture metadata. |
sphinx/_fixtures/twister/twister_report.xml |
Adds Twister report fixture. |
sphinx/_fixtures/twister/qemu_cortex_m3_ti_lm3s6965/zephyr_gnu/tests/kernel/queue/kernel.queue/handler.log |
Adds execution-log fixture. |
sphinx/_fixtures/twister-path/twister.json |
Adds path-filter fixture. |
sphinx/_fixtures/twister-path/twister_report.xml |
Adds path-report fixture. |
sphinx/_fixtures/twister-path/needs.json |
Adds path-related needs. |
sphinx/_fixtures/twister-param/twister.json |
Adds parameterized results. |
sphinx/_fixtures/twister-param/twister_report.xml |
Adds parameterized report. |
sphinx/_fixtures/twister-param/needs.json |
Adds parameterized-test needs. |
sphinx/_fixtures/twister-depends/twister.json |
Adds dependency results. |
sphinx/_fixtures/twister-depends/twister_report.xml |
Adds dependency report. |
sphinx/_fixtures/twister-depends/qemu_x86/zephyr_gnu/tests/kernel/demo/kernel.demo/zephyr/.config |
Adds enabled-config fixture. |
sphinx/_fixtures/twister-depends/qemu_x86/zephyr_gnu/tests/kernel/demo/kernel.demo.soak/zephyr/.config |
Adds soak config fixture. |
sphinx/_fixtures/twister-depends/needs.json |
Adds dependency-aware needs. |
sphinx/_fixtures/twister-depends/mps2_an385/zephyr_gnu/tests/kernel/demo/kernel.demo/zephyr/.config |
Adds disabled-config fixture. |
sphinx/_fixtures/twister-depends/mps2_an385/zephyr_gnu/tests/kernel/demo/kernel.demo.big/zephyr/.config |
Adds platform config fixture. |
sphinx/_fixtures/needs/needs.json |
Adds shared needs fixture. |
sphinx/_fixtures/doxygen/index.xml |
Adds Doxygen index fixture. |
sphinx/_fixtures/doxygen/group__queue__procedures.xml |
Adds procedure fixture. |
sphinx/_fixtures/doxygen/group__queue__api.xml |
Adds API fixture. |
sphinx/_fixtures/doxygen/group__kernel__queue__module.xml |
Adds module fixture. |
sphinx/_fixtures/doxygen-symbols/req.dox |
Adds requirement source fixture. |
sphinx/_fixtures/doxygen-symbols/req_8dox.xml |
Adds requirement XML fixture. |
sphinx/_fixtures/doxygen-symbols/queue.h |
Adds symbol source fixture. |
sphinx/_fixtures/doxygen-symbols/queue_8h.xml |
Adds symbol XML fixture. |
sphinx/_fixtures/doxygen-symbols/index.xml |
Adds symbol index fixture. |
sphinx/_fixtures/doxygen-symbols/group__queue__apis.xml |
Adds API-symbol fixture. |
sphinx/_fixtures/doxygen-symbols/Doxyfile |
Configures symbol fixture generation. |
sphinx/_fixtures/doxygen-qualifier/index.xml |
Adds qualifier index fixture. |
sphinx/_fixtures/doxygen-qualifier/group__m2__module.xml |
Adds second module fixture. |
sphinx/_fixtures/doxygen-qualifier/group__m2____workqueue__api.xml |
Adds second suite fixture. |
sphinx/_fixtures/doxygen-qualifier/group__m1__module.xml |
Adds first module fixture. |
sphinx/_fixtures/doxygen-qualifier/group__m1____workqueue__api.xml |
Adds first suite fixture. |
sphinx/_fixtures/doxygen-kconfig/kd.c |
Adds Kconfig source fixture. |
sphinx/_fixtures/doxygen-kconfig/index.xml |
Adds Kconfig index fixture. |
sphinx/_fixtures/doxygen-kconfig/group__kd__suite.xml |
Adds Kconfig XML fixture. |
sphinx/_fixtures/doxygen-kconfig/Doxyfile |
Configures Kconfig fixture generation. |
sphinx/_extensions/test_coverage.py |
Improves adequacy need output. |
sphinx/_extensions/need_cards.py |
Generates colors and status classes. |
sphinx/_extensions/_tests/test_testreport_path.py |
Updates fixture location. |
sphinx/_extensions/_tests/test_testreport_param.py |
Updates fixture location. |
sphinx/_extensions/_tests/test_testreport_depends.py |
Updates fixture location. |
sphinx/_extensions/_tests/test_test_module.py |
Updates fixture location. |
sphinx/_extensions/_tests/test_symbol_needs.py |
Updates fixture location. |
sphinx/_extensions/_tests/test_suite_qualifier.py |
Updates fixture location. |
sphinx/_extensions/_tests/test_need_cards.py |
Tests card extension behavior. |
sphinx/_extensions/_tests/test_kconfig_depends.py |
Updates fixture location. |
sphinx/_extensions/_tests/test_adequacy.py |
Tests enhanced adequacy output. |
sphinx/_extensions/_tests/roots/test-testreport/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testreport-path/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testreport-param/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testreport-mapping/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testreport-depends/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testmodule/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testmodule-qualifier/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testmodule-partial-mapping/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-testmodule-mapping/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-symbolneeds/conf.py |
Updates fixture path. |
sphinx/_extensions/_tests/roots/test-needcards/index.rst |
Adds card test needs. |
sphinx/_extensions/_tests/roots/test-needcards/conf.py |
Configures card test project. |
sphinx/_extensions/_tests/conftest.py |
Adds shared-module imports. |
README.rst |
Updates test instructions. |
pytest.ini |
Selects both unit-test trees. |
doc/manual/reference/directives-and-roles.rst |
Documents cards and adequacy output. |
doc/manual/howto/run-the-test-suites.rst |
Updates test commands. |
doc/manual/explanation/decisions/0003-engine-unit-suite.rst |
Records test-suite reorganization. |
doc/manual/explanation/architecture/building-blocks.rst |
Documents support modules. |
doc/api/python/support-modules.rst |
Adds support-module API reference. |
doc/api/python/index.rst |
Links support-module reference. |
doc/api/python/extensions.rst |
Separates extension documentation. |
doc/api/conf.py |
Adds support-module import path. |
.ruff.toml |
Excludes generated script-test output. |
.pre-commit-config.yaml |
Updates fixture path comment. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The sphinx-needs layouts show the fields of a need before its text, in a small font, with every field and link at the same weight. The text, the part a reader came for, is last. need_layout() now gives the zdocs need card: a head with the type, the ID, a pill (the status, or the verdict of an adequacy need) and the title; then the text; then the fields and links. fields=[(name, label)] chooses the fields and their labels; hide_backlinks stays. zdocs-needs.css styles a need whose layout name starts with "zdocs", so a document's own layouts keep the sphinx-needs look. The rows keep the sphinx-needs order in the HTML and CSS shows the text first, so the PDF does not change. The need_cards extension gives each card the color of its type from needs_config.toml and adds zd-status-<status> / zd-verdict-<verdict> to the need table, for the pill colors. The need data does not change. The references that the engine writes into a generated need (Depends on, Source, See also, Declared in) go into a need-refs container, which the card shows as one block under the text. Unit 439, acceptance 321/321, zdocs docs 0 warnings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
The body of an adequacy need started with "Verdict partial, evidence
passing, coverage run ...", which repeats the fields, and listed every
other test of every body, up to ten matrix keys each: 2074 keys for
k_sched_lock, which its own tests run anyway.
The need now has the title of its requirement. The body:
* one sentence that says why the verdict is what it is ("The own tests
run 1 of the 2 symbols that coverage can judge. Only other tests run
z_check_stack_sentinel."), adequacy_summary();
* a table with one row per body: the function whose body was read
(z_vrfy_k_msgq_num_used_get), its form and place, the lines the own
tests ran of the lines any test ran, and the number of other test
cases; no table for a requirement without a body;
* the other tests only for a body that the own tests never run: the
places where a @verifies can go. A case is named once, and the cases
that ran the same lines are one group;
* the verifying tests, and the fields the consumer does not declare.
The cells use the roles zd-adq-ok / -miss / -none / -loc (a class of
the same name); zdocs-needs.css colors them in a zdocs card.
adequacy.need_titles() reads the requirement titles from the needs.json
files that the directive already reads. The verdicts and the need data
do not change, apart from the title.
The per-test line ranges of the own tests are not in the body any more.
Unit 451 (+12), acceptance 321/321, zdocs docs 0 warnings.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
tobiaskaestner
force-pushed
the
tkaestner/need-cards
branch
from
October 13, 2026 19:05
93da682 to
9def8c3
Compare
tobiaskaestner
changed the base branch from
main
to
tkaestner/scripts-modules
October 13, 2026 19:09
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
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.
This PR makes the sphinx-needs cards easier to read.
needs_config.toml. The font sizes match the theme. In the HTML, the rows stay in the sphinx-needs order, so the PDF does not change.The module move and the test-suite split were part of this PR before. They are now in #18, which is the base of this PR.
🤖 Generated with Claude Code