sphinx-needs Integration

sphinx-hextra automatically styles sphinx-needs output whenever the extension is enabled. Tables, need blocks, status and type badges all pick up the theme’s colors and rounded corners in both light and dark mode — no configuration required.

The sphinx-needs configuration for this site lives in ubproject.toml and is loaded via needs_from_toml = "ubproject.toml" in conf.py.

Requirements

Requirement: Beautiful by default R_DESIGN_001

status: closed tags: theme links incoming: S_LAYOUT_001

The theme must be visually recognisable as “Hextra on Sphinx” out of the box — no user configuration required beyond html_theme = "sphinx_hextra".

Requirement: Component directives R_CORE_002

status: closed tags: directive links incoming: S_DIRECTIVES_002

Users must be able to drop Hextra-style components (callouts, cards, tabs, steps, filetrees) into their pages using native Sphinx / MyST syntax.

Requirement: sphinx-needs compatibility R_NEEDS_003

status: closed tags: theme links incoming: S_NEEDS_CSS_003

The theme must render sphinx-needs output (tables, need blocks, badges) in a visual style consistent with the rest of the theme.

Specifications

Specification: Hextra layout chrome S_LAYOUT_001

status: closed tags: theme links outgoing: R_DESIGN_001 links incoming: T_BUILD_001

Ship a full custom layout.html with navbar, sidebar, right-hand TOC, and footer, styled after the Hextra Hugo theme.

Specification: Five core directives S_DIRECTIVES_002

status: closed tags: directive links outgoing: R_CORE_002 links incoming: T_DIRECTIVES_002

Implement hextra-callout, hextra-cards/hextra-card, hextra-tabs, hextra-steps, and hextra-filetree as Sphinx directives emitting semantic HTML with stable BEM classnames.

Specification: Scoped needs stylesheet S_NEEDS_CSS_003

status: closed tags: css links outgoing: R_NEEDS_003 links incoming: T_NEEDS_003

Inject a scoped sphinx-hextra-needs.css on pages where sphinx_needs is loaded. The stylesheet restyles needs_table, needs_status, needs_type, and .need blocks using the theme’s CSS variables.

Test cases

Test Case: Theme builds with zero warnings T_BUILD_001

status: closed links outgoing: S_LAYOUT_001

Integration test tests/integration/test_theme_loads.py::test_theme_builds_without_errors asserts the minimal Sphinx project using html_theme = "sphinx_hextra" builds with an empty warning buffer.

Test Case: Every directive renders semantic HTML T_DIRECTIVES_002

status: closed links outgoing: S_DIRECTIVES_002

Integration tests under tests/integration/test_callout.py, test_cards.py, test_tabs.py, test_steps.py, test_filetree.py assert that each directive emits the expected classnames and DOM structure via BeautifulSoup.

Test Case: Needs CSS is loaded only when needed T_NEEDS_003

status: closed links outgoing: S_NEEDS_CSS_003

tests/integration/test_needs_integration.py verifies sphinx-hextra-needs.css is present in pages built against a project with sphinx_needs, and absent otherwise.

Traceability

The needtable directive renders a live overview of every need defined on this page:

ID	Title	Type	Status	Tags	Outgoing
R_CORE_002	Component directives	req	closed	directive
R_DESIGN_001	Beautiful by default	req	closed	theme
R_NEEDS_003	sphinx-needs compatibility	req	closed	theme
S_DIRECTIVES_002	Five core directives	spec	closed	directive	R_CORE_002
S_LAYOUT_001	Hextra layout chrome	spec	closed	theme	R_DESIGN_001
S_NEEDS_CSS_003	Scoped needs stylesheet	spec	closed	css	R_NEEDS_003
T_BUILD_001	Theme builds with zero warnings	test	closed		S_LAYOUT_001
T_DIRECTIVES_002	Every directive renders semantic HTML	test	closed		S_DIRECTIVES_002
T_NEEDS_003	Needs CSS is loaded only when needed	test	closed		S_NEEDS_CSS_003

On this page

• sphinx-needs Integration
  • Requirements
  • Specifications
  • Test cases
  • Traceability