sphinx-ux-badges¶
Alpha
Rendered output is stable. The Python API, CSS class names, and Sphinx config value names may change without a major version bump. Pin your dependency to a specific version range in production.
Shared badge node, HTML visitors, and CSS infrastructure for Sphinx autodoc
extensions. Provides a single BadgeNode and builder API that
sphinx-autodoc-api-style, sphinx-autodoc-pytest-fixtures, and
sphinx-autodoc-fastmcp share instead of reimplementing badges
independently.
$ pip install sphinx-ux-badges
Live demos¶
Every variant rendered by the real build_badge / build_badge_group /
build_toolbar API:
No icon
label build_badge("label")
With icon — left (default, gp-sphinx-badge[data-icon])
readonly mutating build_badge("readonly", icon="🔍")
With icon — right (gp-sphinx-badge–icon-right)
build_badge("readonly", icon="🔍", classes=[SAB.ICON_RIGHT])
Icon-only — 16x16 coloured box (gp-sphinx-badge–icon-only)
build_badge("", style="icon-only", icon="🔍")
Inline-icon — bare emoji inside code chip (gp-sphinx-badge–inline-icon)
some_function() other_func() build_badge("", style="inline-icon", icon="✏️")
Outline (gp-sphinx-badge–outline)
outline outline + icon build_badge("outline", fill="outline")
Dense (gp-sphinx-badge–dense) — compact bordered, dotted underline
dense dense + icon left SAB.DENSE + icon variants
Dense + outline
dense outline dense outline + icon left SAB.DENSE + outline
Underline control modifiers
dense default no underline solid dotted (opt-in) solid (opt-in) SAB.NO_UNDERLINE / SAB.UNDERLINE_SOLID / SAB.UNDERLINE_DOTTED
All sizes — standard pill
xxs xxs+icon xs xs+icon sm sm+icon md md+icon default default+icon lg lg+icon xl xl+icon xxs / xs / sm / md / default / lg / xl
All sizes — dense
xxs xxs+icon xs xs+icon sm sm+icon md md+icon default default+icon lg lg+icon xl xl+icon xxs / xs / sm / md / default / lg / xl (gp-sphinx-badge--dense)
Icon positions — standard (no icon / left / right / icon-only)
function function function: none / left / right / icon-only
fixture fixture fixture: none / left / right / icon-only
config config config: none / left / right / icon-only
directive directive directive: none / left / right / icon-only
Icon positions — dense
function function function (dense): none / left / right
fixture fixture fixture (dense): none / left / right
config config config (dense): none / left / right
directive directive directive (dense): none / left / right
Badge group
alpha beta gamma build_badge_group([...badges...])
Toolbar (push-right in flex heading)
build_toolbar(build_badge_group([...]))
Python API types (gp-sphinx-badge–type-*)
function class method property attribute data exception type alias module
Python API types — dense variant (gp-sphinx-badge–dense)
function class method property attribute data exception type alias module
Python API modifiers (gp-sphinx-badge–mod-*, outlined)
async classmethod staticmethod abstract final
Python API modifiers — dense variant
async classmethod staticmethod abstract final
pytest fixture types (gp-sphinx-badge–type-fixture)
fixture SAB.TYPE_FIXTURE — standard
fixture SAB.TYPE_FIXTURE — dense
pytest fixture scopes (gp-sphinx-badge–scope-*)
session module class
session module class
pytest fixture kinds / states (outlined)
factory override auto deprecated
factory override auto deprecated
Sphinx config (gp-sphinx-badge–type-config / gp-sphinx-badge–mod-rebuild)
config env html standard
config env html dense
docutils (gp-sphinx-badge–type-directive / role / option)
directive role option standard
directive role option dense
Package metadata — maturity
gp-sphinx-badge--meta-alpha / gp-sphinx-badge--meta-beta (filled)
Package metadata — link badges (outline)
GitHub PyPI _link_badge(label, url) — gp-sphinx-badge gp-sphinx-badge--outline gp-sphinx-badge--meta-link <a>
Package metadata — full header row
Working usage examples¶
setup() registers the extension with Sphinx:
add_node()registersBadgeNodewith HTML visitors (visit_badge_html/depart_badge_html).add_css_file()injects the sharedsphinx_ux_badges.cssstylesheet.Downstream extensions call
setup_extension()to load the badge layer:
def setup(app: Sphinx) -> dict[str, Any]:
app.setup_extension("sphinx_ux_badges")
BadgeNode subclasses docutils.nodes.inline, so unregistered
builders (text, LaTeX, man) fall back to visit_inline via Sphinx’s
MRO-based dispatch — no special handling needed.
Build a grouped toolbar in your own directive or transform:
from sphinx_ux_badges import build_badge, build_badge_group, build_toolbar
badge_group = build_badge_group(
[
build_badge(
"readonly",
tooltip="Read-only operation",
classes=["gp-sphinx-fastmcp__safety-readonly"],
),
build_badge(
"tool",
tooltip="FastMCP tool entry",
classes=["gp-sphinx-fastmcp__type-tool"],
),
],
)
toolbar = build_toolbar(badge_group, classes=["my-extension-toolbar"])
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 |
|
Used for |
|---|---|---|
|
|
Python functions (blue) |
|
|
Python classes (indigo) |
|
|
Instance / class / static methods (cyan) |
|
|
Properties (teal) |
|
|
Attributes (slate) |
|
|
Module-level data (grey) |
|
|
Exceptions (rose/red) |
|
|
Type aliases (violet) |
|
|
Modules (green) |
|
|
async modifier (purple outline) |
|
|
classmethod modifier (amber outline) |
|
|
staticmethod modifier (grey outline) |
|
|
abstract modifier (indigo outline) |
|
|
final modifier (emerald outline) |
|
|
deprecated (muted red, shared across domains) |
|
|
pytest fixtures (green) |
|
|
session-scope fixtures (amber) |
|
|
module-scope fixtures (teal) |
|
|
class-scope fixtures (slate) |
|
|
factory fixtures (amber outline) |
|
|
override hooks (violet outline) |
|
|
autouse fixtures (rose outline) |
|
|
Sphinx config values (amber) |
|
|
Sphinx rebuild mode (grey outline) |
|
|
docutils directives (violet) |
|
|
docutils roles (violet) |
|
|
docutils directive options (violet) |
API reference¶
-
class sphinx_ux_badges.BadgeSpec¶
Bases:
objectTyped 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)¶
-
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:
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=())¶
Wrap badges in a group container with inter-badge spacing.
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=())¶
Wrap a badge group in a toolbar (
margin-left: autofor 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¶
Bases:
inlineInline badge rendered as
<span>with ARIA and icon support.Subclasses
nodes.inlineso unregistered builders (text, LaTeX, man) fall back tovisit_inlinevia MRO dispatch inSphinxTranslator.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.classesNoneAdditional CSS classes (plugin prefix + color class).
-
class sphinx_ux_badges._css.SAB¶
Bases:
objectCSS 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'
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 |
|---|---|
|
Badge background color. Extensions set this per badge class (e.g. green for “readonly”). |
|
Badge text color. Falls back to |
|
Border shorthand ( |
|
Font size. Context-aware sizing (headings, body, TOC) overrides this. |
|
Font weight. Default |
|
Vertical and horizontal padding. |
|
Border radius for pill shape. |
|
Gap between the |
|
Subtle inset highlight + shadow for depth on light backgrounds. |
|
Stronger inset shadow variant for dark theme / |
CSS class reference¶
All classes use the sab- prefix (sphinx autodoc badges).
Class |
Applied by |
Description |
|---|---|---|
|
|
Base class. Always present on every badge. |
|
|
Transparent background, inherits text color. |
|
|
16 × 16 colored box with emoji |
|
|
Bare emoji inside a code chip, no background. |
|
|
Flex container with |
|
|
Flex push-right ( |
|
|
Minimum size (status dots, very tight layouts). |
|
|
Extra small (dense tables, tight UI). |
|
|
Small inline badges. |
|
|
Medium — larger than the default but smaller than |
|
|
Large (section titles, callouts). |
|
|
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 ( |
|
|
Body ( |
|
|
TOC sidebar |
|
|
Downstream extensions¶
All colour variants are provided by the shared palette above. Downstream
extensions reference SAB.* constants instead of maintaining their own
sab-* / spf-* / sas-* / sadoc-* colour classes.
Extension |
Badge types used |
|---|---|
Safety tiers (readonly / mutating / destructive), MCP tool type ( |
|
|
|
|
|
|
|
|
Package reference¶
Copyable config snippet
extensions = [
"sphinx_ux_badges",
]
Package metadata
Source on GitHub: sphinx-ux-badges
PyPI: sphinx-ux-badges
Maturity:
Alpha
Registered Surface
sphinx_ux_badges