API Reference¶

Colour palette¶

All semantic badge colours live in sab_palettes.css (registered by this extension). Every sphinx-autodoc-* package uses the SAB.* constants instead of its own colour classes. The live demo below shows every variant.

Colour class	`SAB` constant	Used for
`gp-sphinx-badge--type-function`	`SAB.TYPE_FUNCTION`	Python functions (blue)
`gp-sphinx-badge--type-class`	`SAB.TYPE_CLASS`	Python classes (indigo)
`gp-sphinx-badge--type-method`	`SAB.TYPE_METHOD`	Instance / class / static methods (cyan)
`gp-sphinx-badge--type-property`	`SAB.TYPE_PROPERTY`	Properties (teal)
`gp-sphinx-badge--type-attribute`	`SAB.TYPE_ATTRIBUTE`	Attributes (slate)
`gp-sphinx-badge--type-data`	`SAB.TYPE_DATA`	Module-level data (grey)
`gp-sphinx-badge--type-exception`	`SAB.TYPE_EXCEPTION`	Exceptions (rose/red)
`gp-sphinx-badge--type-typealias`	`SAB.TYPE_TYPEALIAS`	Type aliases (violet)
`gp-sphinx-badge--type-module`	`SAB.TYPE_MODULE`	Modules (green)
`gp-sphinx-badge--mod-async`	`SAB.MOD_ASYNC`	async modifier (purple outline)
`gp-sphinx-badge--mod-classmethod`	`SAB.MOD_CLASSMETHOD`	classmethod modifier (amber outline)
`gp-sphinx-badge--mod-staticmethod`	`SAB.MOD_STATICMETHOD`	staticmethod modifier (grey outline)
`gp-sphinx-badge--mod-abstract`	`SAB.MOD_ABSTRACT`	abstract modifier (indigo outline)
`gp-sphinx-badge--mod-final`	`SAB.MOD_FINAL`	final modifier (emerald outline)
`gp-sphinx-badge--state-deprecated`	`SAB.STATE_DEPRECATED`	deprecated (muted red, shared across domains)
`gp-sphinx-badge--type-fixture`	`SAB.TYPE_FIXTURE`	pytest fixtures (green)
`gp-sphinx-badge--scope-session`	`SAB.SCOPE_SESSION`	session-scope fixtures (amber)
`gp-sphinx-badge--scope-module`	`SAB.SCOPE_MODULE`	module-scope fixtures (teal)
`gp-sphinx-badge--scope-class`	`SAB.SCOPE_CLASS`	class-scope fixtures (slate)
`gp-sphinx-badge--state-factory`	`SAB.STATE_FACTORY`	factory fixtures (amber outline)
`gp-sphinx-badge--state-override`	`SAB.STATE_OVERRIDE`	override hooks (violet outline)
`gp-sphinx-badge--state-autouse`	`SAB.STATE_AUTOUSE`	autouse fixtures (rose outline)
`gp-sphinx-badge--type-config`	`SAB.TYPE_CONFIG`	Sphinx config values (amber)
`gp-sphinx-badge--mod-rebuild`	`SAB.MOD_REBUILD`	Sphinx rebuild mode (grey outline)
`gp-sphinx-badge--type-directive`	`SAB.TYPE_DIRECTIVE`	docutils directives (violet)
`gp-sphinx-badge--type-role`	`SAB.TYPE_ROLE`	docutils roles (violet)
`gp-sphinx-badge--type-option`	`SAB.TYPE_OPTION`	docutils directive options (violet)

API reference¶

class sphinx_ux_badges.BadgeSpec ¶ class[source] class[source] class sphinx_ux_badges.BadgeSpec ¶

Bases: object

Typed badge descriptor used by producer extensions.

Parameters:

text (str) – Visible badge label.
tooltip (str) – Tooltip and aria label for the badge.
icon (str) – Optional icon rendered via ::before.
classes (tuple[str, ...]) – Additional CSS classes for package-specific color and role styling.
style ({"full", "icon-only", "inline-icon"}) – Structural variant.
fill ({"filled", "outline"}) – Visual fill variant.
size (str) – Optional size token: "xxs", "xs", "sm", "md", "lg", or "xl".
tabindex (str) – Focus behavior token forwarded to BadgeNode.

Examples

>>> spec = BadgeSpec("config", tooltip="Sphinx config value")
>>> spec.text
'config'

sphinx_ux_badges.build_badge_from_spec(spec) ¶ function[source] function[source] sphinx_ux_badges.build_badge_from_spec(spec) ¶

Build a BadgeNode from a typed BadgeSpec.

Parameters:: spec (BadgeSpec) – Structured badge description from a producer extension.
Returns:: Renderable badge node.
Return type:: BadgeNode

sphinx_ux_badges.build_badge(text, *, tooltip='', icon='', classes=(), style='full', fill='filled', size='', tabindex='0') ¶ function[source] function[source] sphinx_ux_badges.build_badge(text, *, tooltip='', icon='', classes=(), style='full', fill='filled', size='', tabindex='0') ¶

Build a single badge node.

Parameters:

text (str) – Visible label. Empty string for icon-only badges.
tooltip (str) – Hover text and aria-label.
icon (str) – Emoji character for CSS ::before.
classes (Sequence[str]) – Additional CSS classes (plugin prefix + color class).
style ({“full”, “icon-only”, “inline-icon”}) – Structural variant.
fill ({“filled”, “outline”}) – Visual fill variant.
size (str) – Optional size tier: "xxs", "xs", "sm", "md", "lg", or "xl". Empty string uses the default (no extra class).
tabindex (str) – "0" for focusable, "" to skip.

Return type:

BadgeNode

Examples

>>> b = build_badge("async", tooltip="Asynchronous", classes=[SAB.MOD_ASYNC])
>>> b.astext()
'async'

>>> b = build_badge(
...     "",
...     style="icon-only",
...     classes=["gp-sphinx-fastmcp__safety-readonly"],
... )
>>> SAB.ICON_ONLY in b["classes"]
True

>>> b = build_badge("big", size="lg")
>>> SAB.LG in b["classes"]
True

sphinx_ux_badges.build_badge_group(badges, *, classes=()) ¶ function[source] function[source] sphinx_ux_badges.build_badge_group(badges, *, classes=()) ¶

Wrap badges in a group container with inter-badge spacing.

Parameters:

badges (Sequence[BadgeNode]) – Badge nodes to group.
classes (Sequence[str]) – Additional CSS classes on the group container.

Return type:

nodes.inline

Examples

>>> from sphinx_ux_badges._nodes import BadgeNode
>>> g = build_badge_group([BadgeNode("a"), BadgeNode("b")])
>>> SAB.BADGE_GROUP in g["classes"]
True

sphinx_ux_badges.build_toolbar(badge_group, *, classes=()) ¶ function[source] function[source] sphinx_ux_badges.build_toolbar(badge_group, *, classes=()) ¶

Wrap a badge group in a toolbar (margin-left: auto for flex titles).

Parameters:

badge_group (nodes.inline) – Badge group from build_badge_group().
classes (Sequence[str]) – Additional CSS classes on the toolbar.

Return type:

nodes.inline

Examples

>>> from sphinx_ux_badges._nodes import BadgeNode
>>> g = build_badge_group([BadgeNode("x")])
>>> t = build_toolbar(g, classes=["gp-sphinx-fastmcp__toolbar"])
>>> SAB.TOOLBAR in t["classes"]
True

class sphinx_ux_badges.BadgeNode ¶ class[source] class[source] class sphinx_ux_badges.BadgeNode ¶

Bases: inline

Inline badge rendered as <span> with ARIA and icon support.

Subclasses nodes.inline so unregistered builders (text, LaTeX, man) fall back to visit_inline via MRO dispatch in SphinxTranslator.dispatch_visit.

Examples

>>> b = BadgeNode("hello", badge_tooltip="greeting")
>>> b["badge_tooltip"]
'greeting'

>>> b.astext()
'hello'

Constructor parameters

Parameter	Default	Description
`text`	`""`	Visible label. Empty string for icon-only badges.
`badge_tooltip`	`""`	Hover text and `aria-label`.
`badge_icon`	`""`	Emoji character rendered via CSS `::before`.
`badge_style`	`"full"`	Structural variant: `"full"`, `"icon-only"`, `"inline-icon"`.
`badge_size`	`""`	Optional size: `"xxs"`, `"xs"`, `"sm"`, `"md"`, `"lg"`, or `"xl"`. Empty means default.
`tabindex`	`"0"`	`"0"` for keyboard-focusable, `""` to skip.
`classes`	`None`	Additional CSS classes (plugin prefix + color class).

class sphinx_ux_badges._css.SAB ¶ class[source] class[source] class sphinx_ux_badges._css.SAB ¶

Bases: object

CSS class constants under the gp-sphinx- namespace.

The gp-sphinx- prefix identifies these classes as part of the gp-sphinx workspace. The badge block (gp-sphinx-badge) and its sibling blocks (gp-sphinx-badge-group, gp-sphinx-toolbar) are tier-A shared concepts — any extension may consume them directly, and the theme may restyle them once for every consumer.

Covers both structural variants (size, outline, icon-only) and the unified semantic colour palette from sab_palettes.css (filename is historical).

All consuming sphinx-autodoc-* packages use these constants for shared badge primitives (group, badge, toolbar, type, modifier, state classes). Extension-specific layout and semantic classes live under each package’s own namespace (e.g. gp-sphinx-fastmcp__* for FastMCP tool sections, gp-sphinx-pytest-fixtures__* for fixture-index layout).

Examples

>>> SAB.PREFIX
'gp-sphinx-badge'

>>> SAB.OUTLINE
'gp-sphinx-badge--outline'

>>> SAB.TYPE_METHOD
'gp-sphinx-badge--type-method'

>>> SAB.STATE_AUTOUSE
'gp-sphinx-badge--state-autouse'

sphinx_ux_badges.setup(app) ¶ function[source] function[source] sphinx_ux_badges.setup(app) ¶

Parameters:: app (Sphinx) – Sphinx application.
Returns:: Extension metadata.
Return type:: dict[str, Any]

Examples

>>> from sphinx_ux_badges import setup
>>> callable(setup)
True

CSS custom properties¶

All colors and metrics are exposed as CSS custom properties on :root. Override them in your project’s custom.css or via add_css_file().

Defaults¶

:root {
  /* ── Color hooks (set by downstream extensions) ────── */
  --gp-sphinx-badge-bg: transparent;        /* badge background */
  --gp-sphinx-badge-fg: inherit;            /* badge text color */
  --gp-sphinx-badge-border: none;           /* badge border shorthand */

  /* ── Metrics ───────────────────────────────────────── */
  --gp-sphinx-badge-font-size: 0.75em;
  --gp-sphinx-badge-font-weight: 700;
  --gp-sphinx-badge-padding-v: 0.35em;      /* vertical padding */
  --gp-sphinx-badge-padding-h: 0.65em;      /* horizontal padding */
  --gp-sphinx-badge-radius: 0.25rem;        /* border-radius */
  --gp-sphinx-badge-icon-gap: 0.28rem;      /* gap between icon and label */

  /* ── Depth (inset shadow on solid badges) ──────────── */
  --gp-sphinx-badge-buff-shadow:
    inset 0 1px 0 rgba(255, 255, 255, 0.2),
    inset 0 -1px 2px rgba(0, 0, 0, 0.12);
  --gp-sphinx-badge-buff-shadow-dark-ui:
    inset 0 1px 0 rgba(255, 255, 255, 0.1),
    inset 0 -1px 2px rgba(0, 0, 0, 0.28);
}

Property reference¶

Property	Purpose
`--gp-sphinx-badge-bg`	Badge background color. Extensions set this per badge class (e.g. green for “readonly”).
`--gp-sphinx-badge-fg`	Badge text color. Falls back to `inherit` when unset.
`--gp-sphinx-badge-border`	Border shorthand (`1px solid #...`). Defaults to `none`.
`--gp-sphinx-badge-font-size`	Font size. Context-aware sizing (headings, body, TOC) overrides this.
`--gp-sphinx-badge-font-weight`	Font weight. Default `700` (bold).
`--gp-sphinx-badge-padding-v` / `--gp-sphinx-badge-padding-h`	Vertical and horizontal padding.
`--gp-sphinx-badge-radius`	Border radius for pill shape.
`--gp-sphinx-badge-icon-gap`	Gap between the `::before` icon and the label text.
`--gp-sphinx-badge-buff-shadow`	Subtle inset highlight + shadow for depth on light backgrounds.
`--gp-sphinx-badge-buff-shadow-dark-ui`	Stronger inset shadow variant for dark theme / `prefers-color-scheme: dark`.

CSS class reference¶

All classes use the sab- prefix (sphinx autodoc badges).

Class	Applied by	Description
`gp-sphinx-badge`	`BadgeNode`	Base class. Always present on every badge.
`gp-sphinx-badge--outline`	`build_badge(fill="outline")`	Transparent background, inherits text color.
`gp-sphinx-badge--icon-only`	`build_badge(style="icon-only")`	16 × 16 colored box with emoji `::before`.
`gp-sphinx-badge--inline-icon`	`build_badge(style="inline-icon")`	Bare emoji inside a code chip, no background.
`gp-sphinx-badge-group`	`build_badge_group()`	Flex container with `gap: 0.3rem` between badges.
`gp-sphinx-toolbar`	`build_toolbar()`	Flex push-right (`margin-left: auto`) for title rows.
`gp-sphinx-badge--size-xxs`	`build_badge(size="xxs")` / `BadgeNode(..., badge_size="xxs")`	Minimum size (status dots, very tight layouts).
`gp-sphinx-badge--size-xs`	`build_badge(size="xs")` / `BadgeNode(..., badge_size="xs")`	Extra small (dense tables, tight UI).
`gp-sphinx-badge--size-sm`	`build_badge(size="sm")`	Small inline badges.
`gp-sphinx-badge--size-md`	`build_badge(size="md")`	Medium — larger than the default but smaller than `lg`.
`gp-sphinx-badge--size-lg`	`build_badge(size="lg")`	Large (section titles, callouts).
`gp-sphinx-badge--size-xl`	`build_badge(size="xl")`	Extra large (hero / landing emphasis).

Context-aware sizing¶

Badge size adapts automatically based on where it appears in the document. CSS selectors handle it. Explicit size classes (gp-sphinx-badge--size-xs … gp-sphinx-badge--size-xl) override contextual sizing when present (higher specificity than context rules).

Context	Font size	Selectors
Heading (`h2`, `h3`)	`0.68rem`	`.body h2 .gp-sphinx-badge`, `[role="main"] h3 .gp-sphinx-badge`
Body (`p`, `li`, `td`, `a`)	`0.62rem`	`.body p .gp-sphinx-badge`, `[role="main"] li .gp-sphinx-badge`, etc.
TOC sidebar	`0.58rem`	`.toc-tree .gp-sphinx-badge` (compact, with emoji icons)