sphinx-autodoc-badges¶

Alpha GitHub PyPI

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-autodoc-badges

How it works¶

setup() registers the extension with Sphinx:

add_node() registers BadgeNode with HTML visitors (visit_badge_html / depart_badge_html).
add_css_file() injects the shared sphinx_autodoc_badges.css stylesheet.
Downstream extensions call setup_extension() to load the badge layer:

def setup(app: Sphinx) -> dict[str, Any]:
    app.setup_extension("sphinx_autodoc_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.

Live badge demos¶

Every variant rendered by the real build_badge / build_badge_group / build_toolbar API:

Size variants (xs / sm / default / lg / xl)

xs sm md lg xl build_badge("lg", size="lg")

Filled (default)

label build_badge("label")

with icon build_badge("with icon", icon="\U0001f50d")

Outline

outline build_badge("outline", fill="outline")

Icon-only

build_badge("", style="icon-only", icon="\U0001f50d")

Inline-icon (inside code chips)

some_function() build_badge("", style="inline-icon", icon="\u270f\ufe0f")

Badge group

alpha beta gamma build_badge_group([...badges...])

Toolbar (push-right in flex heading)

build_toolbar(build_badge_group([...]))

API reference¶

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

Build a single badge node.

Return type:

BadgeNode

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 (str) – Structural variant: "full", "icon-only", "inline-icon".
fill (str) – Visual fill: "filled" (default) or "outline".
size (str) – Optional size tier: "xs", "sm", "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=["gas-mod-async"])
>>> b.astext()
'async'

>>> b = build_badge("", style="icon-only", classes=["smf-safety-readonly"])
>>> "sab-icon-only" in b["classes"]
True

>>> b = build_badge("big", size="lg")
>>> "sab-lg" in b["classes"]
True

sphinx_autodoc_badges.build_badge_group(badges, *, classes=())function¶

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

Return type:

inline

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_autodoc_badges._nodes import BadgeNode
>>> g = build_badge_group([BadgeNode("a"), BadgeNode("b")])
>>> "sab-badge-group" in g["classes"]
True

sphinx_autodoc_badges.build_toolbar(badge_group, *, classes=())function¶

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

Return type:

inline

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_autodoc_badges._nodes import BadgeNode
>>> g = build_badge_group([BadgeNode("x")])
>>> t = build_toolbar(g, classes=["smf-toolbar"])
>>> "sab-toolbar" in t["classes"]
True

class sphinx_autodoc_badges.BadgeNodeclass¶

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: `"xs"`, `"sm"`, `"lg"`, or `"xl"`. Empty means default.
`tabindex`	`"0"`	`"0"` for keyboard-focusable, `""` to skip.
`classes`	`None`	Additional CSS classes (plugin prefix + color class).

__init__(text='', *, badge_tooltip='', badge_icon='', badge_style='full', badge_size='', tabindex='0', classes=None, **attributes)method¶

Parameters:

text (str)
badge_tooltip (str)
badge_icon (str)
badge_style (str)
badge_size (str)
tabindex (str)
classes (list[str] | None)
attributes (Any)

Return type:

None

classmethod __new__(*args, **kwargs)classmethod method¶

class sphinx_autodoc_badges._css.SABclass¶

Bases: object

CSS class constants (sab- = sphinx autodoc badges).

Examples

>>> SAB.PREFIX
'sab'

>>> SAB.OUTLINE
'sab-outline'

PREFIX = 'sab'attribute¶

BADGE = 'sab-badge'attribute¶

BADGE_GROUP = 'sab-badge-group'attribute¶

TOOLBAR = 'sab-toolbar'attribute¶

ICON_ONLY = 'sab-icon-only'attribute¶

INLINE_ICON = 'sab-inline-icon'attribute¶

OUTLINE = 'sab-outline'attribute¶

FILLED = 'sab-filled'attribute¶

XS = 'sab-xs'attribute¶

SM = 'sab-sm'attribute¶

LG = 'sab-lg'attribute¶

XL = 'sab-xl'attribute¶

sphinx_autodoc_badges.setup(app)function¶

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

Examples

>>> from sphinx_autodoc_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) ────── */
  --sab-bg: transparent;        /* badge background */
  --sab-fg: inherit;            /* badge text color */
  --sab-border: none;           /* badge border shorthand */

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

  /* ── Depth (inset shadow on solid badges) ──────────── */
  --sab-buff-shadow:
    inset 0 1px 0 rgba(255, 255, 255, 0.2),
    inset 0 -1px 2px rgba(0, 0, 0, 0.12);
  --sab-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
`--sab-bg`	Badge background color. Extensions set this per badge class (e.g. green for “readonly”).
`--sab-fg`	Badge text color. Falls back to `inherit` when unset.
`--sab-border`	Border shorthand (`1px solid #...`). Defaults to `none`.
`--sab-font-size`	Font size. Context-aware sizing (headings, body, TOC) overrides this.
`--sab-font-weight`	Font weight. Default `700` (bold).
`--sab-padding-v` / `--sab-padding-h`	Vertical and horizontal padding.
`--sab-radius`	Border radius for pill shape.
`--sab-icon-gap`	Gap between the `::before` icon and the label text.
`--sab-buff-shadow`	Subtle inset highlight + shadow for depth on light backgrounds.
`--sab-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
`sab-badge`	`BadgeNode`	Base class. Always present on every badge.
`sab-outline`	`build_badge(fill="outline")`	Transparent background, inherits text color.
`sab-icon-only`	`build_badge(style="icon-only")`	16 × 16 colored box with emoji `::before`.
`sab-inline-icon`	`build_badge(style="inline-icon")`	Bare emoji inside a code chip, no background.
`sab-badge-group`	`build_badge_group()`	Flex container with `gap: 0.3rem` between badges.
`sab-toolbar`	`build_toolbar()`	Flex push-right (`margin-left: auto`) for title rows.
`sab-xs`	`build_badge(size="xs")` / `BadgeNode(..., badge_size="xs")`	Extra small (dense tables, tight UI).
`sab-sm`	`build_badge(size="sm")`	Small inline badges.
`sab-lg`	`build_badge(size="lg")`	Large (section titles, callouts).
`sab-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 (sab-xs … sab-xl) override contextual sizing when present (higher specificity than context rules).

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

Downstream extensions¶

Each extension adds its own CSS color layer on top of the shared base:

Extension	Prefix	Badge types
sphinx-autodoc-fastmcp	`smf-`	Safety tiers (readonly / mutating / destructive), MCP tool type
sphinx-autodoc-api-style	`gas-`	Python object types (function, class, method, …), modifiers (async, deprecated, …)
sphinx-autodoc-pytest-fixtures	`spf-`	Fixture scopes (session, module, function), kind badges (autouse, yield)

Package reference¶

Copyable config snippet

extensions = [
    "sphinx_autodoc_badges",
]

Package metadata

Source on GitHub: sphinx-autodoc-badges
PyPI: sphinx-autodoc-badges
Maturity: Alpha

Registered Surface

sphinx_autodoc_badges

Source on GitHub · PyPI