Skip to content

Commit 2eff6b8

Browse files
committed
docs(AGENTS[architecture]): require package CSS self-containment
why: The STATE_DEPRECATED fixture-muting regression on this branch was a stealth cross-package CSS dep — sphinx-autodoc-pytest-fixtures emitted gp-sphinx-badge--state-deprecated on fixture containers, but the muting rule only existed in sphinx-autodoc-api-style's CSS. Standalone installs of pytest-fixtures lost the visual signal silently. Writing the rule down prevents the next cross-package selector from slipping in unnoticed. what: - Add a "Package CSS self-containment" subsection under Code Architecture. States the principle (each package's CSS styles every class that package's Python emits) and draws the reuse-vs-dependence distinction so shared classes like gp-sphinx-badge stay legitimate while sibling-package CSS dependencies do not.
1 parent de16431 commit 2eff6b8

1 file changed

Lines changed: 11 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,17 @@ gp_sphinx/
141141
- `DEFAULT_FONT_FAMILIES` dict
142142
- Shared sidebar configuration
143143

144+
### Package CSS self-containment
145+
146+
A workspace package's own CSS must style every class its Python code
147+
emits. If a directive appends `SAB.X` (or any gp-sphinx-* class) to a
148+
node, the package's own CSS file carries a rule targeting `SAB.X`.
149+
Cross-package **reuse** of a shared class (e.g., `gp-sphinx-badge`
150+
styled in `sphinx-ux-badges`) is fine; cross-package **dependence**
151+
where your feature only renders correctly because a sibling package
152+
happens to be loaded — is not. A downstream user installing a single
153+
extension standalone must get the correct visual result.
154+
144155
## Testing Strategy
145156

146157
All tests are plain functions (`def test_*`). No `class TestFoo:` groupings. Every test

0 commit comments

Comments
 (0)