Skip to content

Commit aa664ff

Browse files
tonytony
committed
css(refactor[namespace]): rename sab-/smf-/spf-/api- to gp-sphinx-* across workspace
why: The four opaque three-letter CSS prefixes (sab-, smf-, spf-, api-) gave no hint that classes came from gp-sphinx, which package owned them, or what tier they belonged to. The new scheme uses a self-documenting two-tier BEM namespace rooted at `gp-sphinx-`: - Tier A (shared concepts): gp-sphinx-badge, gp-sphinx-badge-group, gp-sphinx-toolbar, gp-sphinx-api-* (the layout primitives every extension reuses). - Tier B (package-owned): gp-sphinx-fastmcp__*, gp-sphinx-pytest-fixtures__*. Modifiers use axis-value pairs (--size-xs, --type-function, --safety-readonly). CSS authors chain selectors (.gp-sphinx-badge.gp-sphinx-badge--dense) to preserve the existing 0,3,0 specificity. CSS custom properties we own (--sab-*, --smf-*, --badge-safety-*, --api-signature-indent) are renamed to match (--gp-sphinx-badge-*, --gp-sphinx-fastmcp-*, --gp-sphinx-fastmcp-safety-*, --gp-sphinx-api-signature-indent). Furo-owned variables (--color-api-*, --font-stack--monospace, etc.) stay untouched. Because all 12 packages publish together and there are no external consumers to deprecate against, this ships as a single atomic rename — no dual-emit, no ClassPair, no legacy selectors, no version bumps, no migration guide. what: - Rewrite SAB (56 attrs) and _CSS (11 attrs) constant containers with new string values; keep class names for call-site stability. The PREFIX attribute now holds the new root (gp-sphinx-badge / gp-sphinx-fastmcp). - Create new _css.py containers: SPF in sphinx-autodoc-pytest-fixtures and API in sphinx-ux-autodoc-layout. Migrate every bare literal in _index.py, _cards.py, _nodes.py, _transforms.py, _visitors.py, _sections.py to the new constants. Re-export API via sphinx_ux_autodoc_layout.__init__. - Rewrite all 6 CSS files (sphinx_ux_badges.css, sab_palettes.css, api_style.css, layout.css, sphinx_autodoc_pytest_fixtures.css, sphinx_autodoc_fastmcp.css). Preserve every chained-selector composition so specificity parity stays at 0,3,0. - Rename --sab-*, --smf-*, --badge-safety-*, --api-signature-indent CSS custom properties to --gp-sphinx-badge-*, --gp-sphinx-fastmcp-*, --gp-sphinx-fastmcp-safety-*, --gp-sphinx-api-signature-indent. - Rewrite the 8 .api-* DOM selectors in sphinx_ux_autodoc_layout/_static/js/layout.js. - Rename the two MyST directives that participate in the docs build: sab-badge-demo → gp-sphinx-badge-demo (in sab_demo.py + gallery.md) sab-package-meta → gp-sphinx-package-meta (in sab_meta.py + every docs/packages/*.md header). - Update every test assertion (`assert "sab-badge" in classes`, etc.) to the new names across tests/ext/{layout,fastmcp,pytest_fixtures, badges,api_style,autodoc_docutils,autodoc_sphinx}/. Regenerate all 11 snapshots in tests/**/__snapshots__/*.ambr via `uv run pytest --snapshot-update`. - Update 12 docs/packages/*.md files + gallery.md + sphinx-ux-badges README for the new class/directive names. - Verified: ruff + mypy clean, py.test 944 passed / 3 skipped, `just build-docs` succeeds, rendered HTML confirms new classes (e.g. `class="gp-sphinx-badge gp-sphinx-badge--dense gp-sphinx-fastmcp__safety-readonly …"`).
1 parent cdd9cd6 commit aa664ff

69 files changed

Lines changed: 1574 additions & 1243 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/_ext/package_reference.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -685,7 +685,7 @@ def maturity_badge(maturity: str) -> str:
685685
"""Return a sphinx-design badge role for use in grid markdown output.
686686
687687
Used only in :func:`workspace_package_grid_markdown` which produces raw
688-
MyST markdown strings. Per-page package headers use the ``sab-package-meta``
688+
MyST markdown strings. Per-page package headers use the ``gp-sphinx-package-meta``
689689
directive (see ``docs/_ext/sab_meta.py``) which emits SAB-native badges.
690690
691691
Examples

‎docs/_ext/sab_demo.py‎

Lines changed: 50 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
5151
)
5252
)
5353

54-
result.append(_section("With icon — left (default, sab-badge[data-icon])"))
54+
result.append(
55+
_section("With icon — left (default, gp-sphinx-badge[data-icon])")
56+
)
5557
result.append(
5658
_row(
5759
build_badge("readonly", icon="\U0001f50d", tooltip="Icon on left"),
@@ -65,7 +67,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
6567
)
6668
)
6769

68-
result.append(_section("With icon — right (sab-icon-right)"))
70+
result.append(_section("With icon — right (gp-sphinx-badge--icon-right)"))
6971
result.append(
7072
_row(
7173
build_badge(
@@ -84,7 +86,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
8486
)
8587
)
8688

87-
result.append(_section("Icon-only — 16x16 coloured box (sab-icon-only)"))
89+
result.append(
90+
_section("Icon-only — 16x16 coloured box (gp-sphinx-badge--icon-only)")
91+
)
8892
result.append(
8993
_row(
9094
build_badge(
@@ -112,7 +116,10 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
112116
)
113117

114118
result.append(
115-
_section("Inline-icon — bare emoji inside code chip (sab-inline-icon)")
119+
_section(
120+
"Inline-icon — bare emoji inside code chip"
121+
" (gp-sphinx-badge--inline-icon)"
122+
)
116123
)
117124
wrapper = nodes.paragraph()
118125
wrapper += build_badge(
@@ -136,7 +143,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
136143
wrapper += nodes.literal(text='build_badge("", style="inline-icon", icon="✏️")')
137144
result.append(wrapper)
138145

139-
result.append(_section("Outline (sab-outline)"))
146+
result.append(_section("Outline (gp-sphinx-badge--outline)"))
140147
result.append(
141148
_row(
142149
build_badge("outline", fill="outline", tooltip="Outline, no bg"),
@@ -158,7 +165,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
158165
)
159166

160167
result.append(
161-
_section("Dense (sab-dense) — compact bordered, dotted underline")
168+
_section(
169+
"Dense (gp-sphinx-badge--dense) — compact bordered, dotted underline"
170+
)
162171
)
163172
result.append(
164173
_row(
@@ -237,25 +246,25 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
237246
build_badge(
238247
"no underline",
239248
icon="\U0001f50d",
240-
tooltip="Dense + sab-no-underline",
249+
tooltip="Dense + gp-sphinx-badge--underline-none",
241250
classes=[SAB.DENSE, SAB.NO_UNDERLINE, SAB.TYPE_CLASS],
242251
),
243252
build_badge(
244253
"solid",
245254
icon="\U0001f50d",
246-
tooltip="Dense + sab-underline-solid",
255+
tooltip="Dense + gp-sphinx-badge--underline-solid",
247256
classes=[SAB.DENSE, SAB.UNDERLINE_SOLID, SAB.TYPE_FIXTURE],
248257
),
249258
build_badge(
250259
"dotted (opt-in)",
251260
icon="\U0001f50d",
252-
tooltip="Standard pill + sab-underline-dotted",
261+
tooltip="Standard pill + gp-sphinx-badge--underline-dotted",
253262
classes=[SAB.UNDERLINE_DOTTED, SAB.TYPE_CONFIG],
254263
),
255264
build_badge(
256265
"solid (opt-in)",
257266
icon="\U0001f50d",
258-
tooltip="Standard pill + sab-underline-solid",
267+
tooltip="Standard pill + gp-sphinx-badge--underline-solid",
259268
classes=[SAB.UNDERLINE_SOLID, SAB.TYPE_DIRECTIVE],
260269
),
261270
label=("SAB.NO_UNDERLINE / SAB.UNDERLINE_SOLID / SAB.UNDERLINE_DOTTED"),
@@ -450,7 +459,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
450459
tooltip="Extra large dense + icon",
451460
classes=[SAB.DENSE, SAB.TYPE_CONFIG],
452461
),
453-
label="xxs / xs / sm / md / default / lg / xl (sab-dense)",
462+
label="xxs / xs / sm / md / default / lg / xl (gp-sphinx-badge--dense)",
454463
)
455464
)
456465

@@ -560,7 +569,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
560569
]
561570
)
562571
)
563-
heading_container = nodes.container(classes=["sab-demo-toolbar-heading"])
572+
heading_container = nodes.container(
573+
classes=["gp-sphinx-badge-demo-toolbar-heading"]
574+
)
564575
heading_p = nodes.paragraph()
565576
heading_p += nodes.strong(text="Example heading ")
566577
heading_p += tb
@@ -570,7 +581,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
570581

571582
# ── Python API type palette (standard + dense) ───────────
572583

573-
result.append(_section("Python API types (sab-type-*)"))
584+
result.append(_section("Python API types (gp-sphinx-badge--type-*)"))
574585
py_types = [
575586
("function", SAB.TYPE_FUNCTION, "Python function"),
576587
("class", SAB.TYPE_CLASS, "Python class"),
@@ -592,7 +603,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
592603
type_row += nodes.Text(" ")
593604
result.append(type_row)
594605

595-
result.append(_section("Python API types — dense variant (sab-dense)"))
606+
result.append(
607+
_section("Python API types — dense variant (gp-sphinx-badge--dense)")
608+
)
596609
type_dense_row = nodes.paragraph()
597610
for label, css_class, tooltip in py_types:
598611
type_dense_row += build_badge(
@@ -603,7 +616,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
603616
type_dense_row += nodes.Text(" ")
604617
result.append(type_dense_row)
605618

606-
result.append(_section("Python API modifiers (sab-mod-*, outlined)"))
619+
result.append(
620+
_section("Python API modifiers (gp-sphinx-badge--mod-*, outlined)")
621+
)
607622
py_mods = [
608623
("async", SAB.MOD_ASYNC, "Asynchronous"),
609624
("classmethod", SAB.MOD_CLASSMETHOD, "Class method"),
@@ -636,7 +651,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
636651

637652
# ── pytest fixture palette ───────────────────────────────
638653

639-
result.append(_section("pytest fixture types (sab-type-fixture)"))
654+
result.append(_section("pytest fixture types (gp-sphinx-badge--type-fixture)"))
640655
result.append(
641656
_row(
642657
build_badge(
@@ -658,7 +673,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
658673
)
659674
)
660675

661-
result.append(_section("pytest fixture scopes (sab-scope-*)"))
676+
result.append(_section("pytest fixture scopes (gp-sphinx-badge--scope-*)"))
662677
scope_row = nodes.paragraph()
663678
scope_dense_row = nodes.paragraph()
664679
for scope in ("session", "module", "class"):
@@ -709,7 +724,12 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
709724

710725
# ── Sphinx config palette ────────────────────────────────
711726

712-
result.append(_section("Sphinx config (sab-type-config / sab-mod-rebuild)"))
727+
result.append(
728+
_section(
729+
"Sphinx config"
730+
" (gp-sphinx-badge--type-config / gp-sphinx-badge--mod-rebuild)"
731+
)
732+
)
713733
result.append(
714734
_row(
715735
build_badge(
@@ -757,7 +777,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
757777

758778
# ── docutils palette ─────────────────────────────────────
759779

760-
result.append(_section("docutils (sab-type-directive / role / option)"))
780+
result.append(
781+
_section("docutils (gp-sphinx-badge--type-directive / role / option)")
782+
)
761783
result.append(
762784
_row(
763785
build_badge(
@@ -806,7 +828,9 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
806828
_row(
807829
_maturity_badge("Alpha"),
808830
_maturity_badge("Beta"),
809-
label="sab-meta-alpha / sab-meta-beta (filled)",
831+
label=(
832+
"gp-sphinx-badge--meta-alpha / gp-sphinx-badge--meta-beta (filled)"
833+
),
810834
)
811835
)
812836

@@ -823,7 +847,10 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
823847
)
824848
link_row += nodes.Text(" ")
825849
link_row += nodes.literal(
826-
text="_link_badge(label, url) — sab-badge sab-outline sab-meta-link <a>",
850+
text=(
851+
"_link_badge(label, url) — gp-sphinx-badge"
852+
" gp-sphinx-badge--outline gp-sphinx-badge--meta-link <a>"
853+
),
827854
)
828855
result.append(link_row)
829856

@@ -846,7 +873,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
846873

847874

848875
def setup(app: Sphinx) -> dict[str, t.Any]:
849-
"""Register the ``sab-badge-demo`` directive."""
850-
app.add_directive("sab-badge-demo", BadgeDemoDirective)
876+
"""Register the ``gp-sphinx-badge-demo`` directive."""
877+
app.add_directive("gp-sphinx-badge-demo", BadgeDemoDirective)
851878
app.add_css_file("css/sab_demo.css")
852879
return {"version": "0.1", "parallel_read_safe": True}

‎docs/_ext/sab_meta.py‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
1313
with::
1414
15-
```{sab-package-meta} sphinx-autodoc-api-style
15+
```{gp-sphinx-package-meta} sphinx-autodoc-api-style
1616
```
1717
1818
The directive looks up the package's maturity, GitHub URL, and PyPI URL
@@ -47,7 +47,8 @@ def _link_badge(label: str, url: str) -> nodes.reference:
4747
"""Return an anchor node styled as an outline SAB badge."""
4848
ref = nodes.reference("", label, refuri=url, internal=False)
4949
# Apply badge classes directly on the anchor node so it renders as
50-
# <a class="sab-badge sab-outline sab-meta-link …" href="…">label</a>
50+
# <a class="gp-sphinx-badge gp-sphinx-badge--outline
51+
# gp-sphinx-badge--meta-link …" href="…">label</a>
5152
ref["classes"].extend([SAB.BADGE, SAB.OUTLINE, SAB.META_LINK])
5253
return ref
5354

@@ -97,6 +98,6 @@ def run(self) -> list[nodes.Node]:
9798

9899

99100
def setup(app: Sphinx) -> dict[str, t.Any]:
100-
"""Register the ``sab-package-meta`` directive."""
101-
app.add_directive("sab-package-meta", PackageMetaBadgesDirective)
101+
"""Register the ``gp-sphinx-package-meta`` directive."""
102+
app.add_directive("gp-sphinx-package-meta", PackageMetaBadgesDirective)
102103
return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}

‎docs/_static/css/sab_demo.css‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.sab-demo-toolbar-heading > p {
1+
.gp-sphinx-badge-demo-toolbar-heading > p {
22
display: flex;
33
align-items: center;
44
gap: 0.45rem;

‎docs/gallery.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ disclosure widget.
9999
The full badge system — types, modifiers, sizes, and variants — rendered by
100100
the real `build_badge` / `build_badge_group` / `build_toolbar` API:
101101

102-
```{sab-badge-demo}
102+
```{gp-sphinx-badge-demo}
103103
```
104104

105105
---

‎docs/packages/gp-sphinx.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# gp-sphinx
22

3-
```{sab-package-meta} gp-sphinx
3+
```{gp-sphinx-package-meta} gp-sphinx
44
```
55

66
:::{admonition} Alpha

‎docs/packages/sphinx-autodoc-api-style.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# sphinx-autodoc-api-style
44

5-
```{sab-package-meta} sphinx-autodoc-api-style
5+
```{gp-sphinx-package-meta} sphinx-autodoc-api-style
66
```
77

88
:::{admonition} Alpha
@@ -134,22 +134,22 @@ This extension uses:
134134

135135
| Object type | `SAB` constant | CSS class |
136136
|---|---|---|
137-
| `function` | `SAB.TYPE_FUNCTION` | `sab-type-function` |
138-
| `class` | `SAB.TYPE_CLASS` | `sab-type-class` |
139-
| `method` | `SAB.TYPE_METHOD` | `sab-type-method` |
140-
| `property` | `SAB.TYPE_PROPERTY` | `sab-type-property` |
141-
| `attribute` | `SAB.TYPE_ATTRIBUTE` | `sab-type-attribute` |
142-
| `data` | `SAB.TYPE_DATA` | `sab-type-data` |
143-
| `exception` | `SAB.TYPE_EXCEPTION` | `sab-type-exception` |
137+
| `function` | `SAB.TYPE_FUNCTION` | `gp-sphinx-badge--type-function` |
138+
| `class` | `SAB.TYPE_CLASS` | `gp-sphinx-badge--type-class` |
139+
| `method` | `SAB.TYPE_METHOD` | `gp-sphinx-badge--type-method` |
140+
| `property` | `SAB.TYPE_PROPERTY` | `gp-sphinx-badge--type-property` |
141+
| `attribute` | `SAB.TYPE_ATTRIBUTE` | `gp-sphinx-badge--type-attribute` |
142+
| `data` | `SAB.TYPE_DATA` | `gp-sphinx-badge--type-data` |
143+
| `exception` | `SAB.TYPE_EXCEPTION` | `gp-sphinx-badge--type-exception` |
144144

145145
| Modifier | `SAB` constant | CSS class |
146146
|---|---|---|
147-
| `async` | `SAB.MOD_ASYNC` | `sab-mod-async` |
148-
| `classmethod` | `SAB.MOD_CLASSMETHOD` | `sab-mod-classmethod` |
149-
| `staticmethod` | `SAB.MOD_STATICMETHOD` | `sab-mod-staticmethod` |
150-
| `abstract` | `SAB.MOD_ABSTRACT` | `sab-mod-abstract` |
151-
| `final` | `SAB.MOD_FINAL` | `sab-mod-final` |
152-
| `deprecated` | `SAB.STATE_DEPRECATED` | `sab-state-deprecated` |
147+
| `async` | `SAB.MOD_ASYNC` | `gp-sphinx-badge--mod-async` |
148+
| `classmethod` | `SAB.MOD_CLASSMETHOD` | `gp-sphinx-badge--mod-classmethod` |
149+
| `staticmethod` | `SAB.MOD_STATICMETHOD` | `gp-sphinx-badge--mod-staticmethod` |
150+
| `abstract` | `SAB.MOD_ABSTRACT` | `gp-sphinx-badge--mod-abstract` |
151+
| `final` | `SAB.MOD_FINAL` | `gp-sphinx-badge--mod-final` |
152+
| `deprecated` | `SAB.STATE_DEPRECATED` | `gp-sphinx-badge--state-deprecated` |
153153

154154
See {doc}`sphinx-ux-badges` for the full shared palette.
155155

‎docs/packages/sphinx-autodoc-argparse.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# sphinx-autodoc-argparse
22

3-
```{sab-package-meta} sphinx-autodoc-argparse
3+
```{gp-sphinx-package-meta} sphinx-autodoc-argparse
44
```
55

66
Modern Sphinx extension for documenting `argparse` CLIs. The base package

‎docs/packages/sphinx-autodoc-docutils.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# sphinx-autodoc-docutils
22

3-
```{sab-package-meta} sphinx-autodoc-docutils
3+
```{gp-sphinx-package-meta} sphinx-autodoc-docutils
44
```
55

66
:::{admonition} Alpha

‎docs/packages/sphinx-autodoc-fastmcp.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# sphinx-autodoc-fastmcp
44

5-
```{sab-package-meta} sphinx-autodoc-fastmcp
5+
```{gp-sphinx-package-meta} sphinx-autodoc-fastmcp
66
```
77

88
:::{admonition} Alpha

0 commit comments

Comments
 (0)