Gallery

Every example on this page is rendered live from the same extensions and theme your project gets out of the box. Nothing is mocked — the output below is the real autodoc pipeline.

---

Python API

Badges, type hints, and card layout working together on standard Python domain directives.

Functions

gp_demo_api.demo_function(name, count=1)

function

function

gp_demo_api.demo_function(name, count=1)

Plain function. Shows function type badge.

Parameters:

• name (str) – The name to repeat.

• count (int) – Number of repetitions.

Returns:

A list of repeated names.

Return type:

list[str]

async gp_demo_api.demo_async_function(url)

async function

async function

async gp_demo_api.demo_async_function(url)

Asynchronous function. Shows async + function badges.

Parameters:

url (str) – The URL to fetch.

Returns:

The fetched content.

Return type:

bytes

gp_demo_api.demo_deprecated_function()

deprecated function

deprecated function

gp_demo_api.demo_deprecated_function()

Do nothing (deprecated placeholder).

Shows deprecated + function badges.

Deprecated since version 2.0: Use demo_function() instead.

Return type:

None

Module data

gp_demo_api.DEMO_CONSTANT: int = 42

data

data

gp_demo_api.DEMO_CONSTANT: int = 42

Module-level constant. Shows data type badge.

Exceptions

exception gp_demo_api.DemoError

exception

exception

exception gp_demo_api.DemoError

Bases: Exception

Custom exception class. Shows exception type badge.

Raised when a demo operation fails unexpectedly.

Classes

class gp_demo_api.DemoClass

class

class

class gp_demo_api.DemoClass

Bases: object

Demonstration class with various method types.

Shows class type badge on the class itself, and per-method badges for each method kind.

Parameters:

value (str) – Initial value for the demo instance.

demo_attr: str = 'hello'

attribute

attribute

demo_attr: str = 'hello'

Class attribute. Shows attribute type badge.

__init__(value)

method

method

__init__(value)

Parameters:

value (str)

Return type:

None

regular_method(x)

method

method

regular_method(x)

Regular instance method. Shows method type badge.

Parameters:

x (int) – Input value.

Returns:

String representation.

Return type:

str

classmethod from_int(n)

classmethod method

classmethod method

classmethod from_int(n)

Class method. Shows classmethod + method badges.

Parameters:

n (int) – Integer to convert.

Returns:

A new instance.

Return type:

DemoClass

static utility(a, b)

staticmethod method

staticmethod method

static utility(a, b)

Add two integers. Shows staticmethod + method badges.

Parameters:

• a (int) – First operand.

• b (int) – Second operand.

Returns:

Sum of operands.

Return type:

int

property computed: str

property

property

property computed: str

Computed property. Shows property type badge.

Returns:

The uppercased value.

Return type:

str

async async_method()

async method

async method

async async_method()

Asynchronous method. Shows async + method badges.

Return type:

None

deprecated_method()

deprecated method

deprecated method

deprecated_method()

Do nothing (deprecated placeholder).

Shows deprecated + method badges.

Deprecated since version 1.5: Use regular_method() instead.

Return type:

None

Abstract base classes

class gp_demo_api.DemoAbstractBase

class

class

class gp_demo_api.DemoAbstractBase

Bases: ABC

Abstract base class. Shows class type badge.

Subclass this to provide concrete implementations.

abstractmethod must_implement()

abstract method

abstract method

abstractmethod must_implement()

Abstract method. Shows abstract + method badges.

Returns:

Implementation-specific value.

Return type:

str

_abc_impl = <_abc._abc_data object>

attribute

attribute

_abc_impl = <_abc._abc_data object>

abstractmethod async async_abstract()

abstract async method

abstract async method

abstractmethod async async_abstract()

Async abstract method. Shows async + abstract + method badges.

Return type:

None

---

Layout regions and parameter folding

Large parameter lists fold automatically. The class below has 13 parameters (above the default threshold of 10), so its field list is collapsed into a disclosure widget.

Class with members (regions + fold)

class api_demo_layout.LayoutDemo

class

class

class api_demo_layout.LayoutDemo

Bases: object

A class demonstrating all layout regions.

The class docstring forms the narrative region. The parameter field list below forms the fields region (folded if large enough). Nested methods form the members region.

Parameters (13)

Parameters:

• host (str) – Server hostname.

• port (int) – Server port number.

• username (str) – Authentication username.

• password (str) – Authentication password.

• database (str) – Database name.

• timeout (float) – Connection timeout in seconds.

• retries (int) – Number of connection retries.

• ssl (bool) – Enable SSL/TLS.

• pool_size (int) – Connection pool size.

• pool_timeout (float) – Pool checkout timeout.

• echo (bool) – Log all SQL statements.

• encoding (str) – Character encoding.

• isolation_level (str) – Transaction isolation level.

__init__(host, [...])

method

method

__init__(host, [...])

Parameters (14)

Parameters:

• host (str)

• port (int)

• username (str)

• password (str)

• database (str)

• timeout (float)

• retries (int)

• ssl (bool)

• pool_size (int)

• pool_timeout (float)

• echo (bool)

• encoding (str)

• isolation_level (str)

Return type:

None

connect()

method

method

connect()

Open a connection to the server.

Returns:

True if connection succeeded.

Return type:

bool

execute(query, params=None)

method

method

execute(query, params=None)

Execute a query and return results.

Parameters:

• query (str) – SQL query string.

• params (dict[str, str] | None) – Query parameters.

Returns:

Query result rows.

Return type:

list[dict[str, str]]

close()

method

method

close()

Close the connection.

Return type:

None

Small function (no fold)

api_demo_layout.compact_function(name, value=0)

function

function

api_demo_layout.compact_function(name, value=0)

Format a name-value pair.

This should render without any fold – just a narrative region followed by a fields region.

Parameters:

• name (str) – The item name.

• value (int) – The item value.

Returns:

Formatted result.

Return type:

str

---

Badge palette

The full badge system — types, modifiers, sizes, and variants — 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)

readonly mutating 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 outline + icon right build_badge("outline", fill="outline")

Dense (gp-sphinx-badge–dense) — compact bordered, dotted underline

dense dense + icon left dense + icon right SAB.DENSE + icon variants

Dense + outline

dense outline dense outline + icon left dense outline + icon right SAB.DENSE + outline

Underline control modifiers

dense default dense icon right 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 function: none / left / right / icon-only

fixture fixture fixture fixture: none / left / right / icon-only

config config config config: none / left / right / icon-only

directive directive directive directive: none / left / right / icon-only

Icon positions — dense

function function function function (dense): none / left / right

fixture fixture fixture fixture (dense): none / left / right

config config config config (dense): none / left / right

directive directive directive directive (dense): none / left / right

Badge group

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

Toolbar (push-right in flex heading)

Example heading readonly tool

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

Alpha Beta 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

Alpha GitHub PyPI

---

FastMCP tool cards

Tool documentation with safety badges and parameter tables.

list_sessions

list_sessions

readonly tool

readonly tool

list_sessions

List active sessions for one server.

Returns:

list[str]

create_session

create_session

mutating tool

mutating tool

create_session

Create one session and return the created record.

Returns:

dict[str, str | int | bool]

delete_session

delete_session

destructive tool

destructive tool

delete_session

Delete one session from the server.

Returns:

bool

Parameter table

Parameters

Parameter	Type	Required	Default	Description
name	str	yes	—	Session name to create.
window_count	int	no	1	Initial number of windows.
detached	bool	no	False	Whether to create the session detached from the current client.

Tool summary

Inspect

Read state without changing anything.

Tool	Description
list_sessions	List active sessions for one server.

Act

Create or modify objects.

Tool	Description
create_session	Create one session and return the created record.

Destroy

Remove objects; not reversible.

Tool	Description
delete_session	Delete one session from the server.

---

pytest fixtures

Fixture reference

fixture spf_demo_fixtures.demo_plain → str

fixture

fixture

fixture spf_demo_fixtures.demo_plain → str

Plain function-scope resource. Shows FIXTURE badge only.

fixture spf_demo_fixtures.demo_session → str

session fixture

session fixture

fixture spf_demo_fixtures.demo_session → str

Session-scoped resource. Shows SESSION + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

fixture spf_demo_fixtures.demo_module → str

module fixture

module fixture

fixture spf_demo_fixtures.demo_module → str

Module-scoped resource. Shows MODULE + FIXTURE badges.

fixture spf_demo_fixtures.demo_class → str

class fixture

class fixture

fixture spf_demo_fixtures.demo_class → str

Class-scoped resource. Shows CLASS + FIXTURE badges.

fixture spf_demo_fixtures.demo_factory → type[str]

factory fixture

factory fixture

fixture spf_demo_fixtures.demo_factory → type[str]

Return a callable (factory kind). Shows FACTORY + FIXTURE badges.

def test_example(demo_factory: type[str]) -> None:
    obj = demo_factory()
    assert obj is not None

fixture spf_demo_fixtures.demo_override_hook → str

fixture

fixture

fixture spf_demo_fixtures.demo_override_hook → str

Override hook — customise in conftest.py. Shows OVERRIDE + FIXTURE badges.

fixture spf_demo_fixtures.demo_autouse → None

auto fixture

auto fixture

fixture spf_demo_fixtures.demo_autouse → None

Autouse fixture. Shows AUTO + FIXTURE badges.

Autouse:

yes — runs automatically for every test

Note

No request needed — this fixture runs automatically for every test.

fixture spf_demo_fixtures.demo_deprecated → str

fixture

fixture

fixture spf_demo_fixtures.demo_deprecated → str

Return a value (deprecated since 1.0, replaced by demo_plain).

This fixture is documented with the deprecated RST option so the demo page can show the DEPRECATED + FIXTURE badge combination.

fixture spf_demo_fixtures.demo_session_factory → type[str]

session factory fixture

session factory fixture

fixture spf_demo_fixtures.demo_session_factory → type[str]

Session-scoped factory. Shows SESSION + FACTORY + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

def test_example(demo_session_factory: type[str]) -> None:
    obj = demo_session_factory()
    assert obj is not None

fixture spf_demo_fixtures.demo_session_autouse → None

session auto fixture

session auto fixture

fixture spf_demo_fixtures.demo_session_autouse → None

Session-scoped autouse. Shows SESSION + AUTO + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Autouse:

yes — runs automatically for every test

Note

No request needed — this fixture runs automatically for every test.

---

Sphinx config values

demo_theme_accent

config html

config html

demo_theme_accent

Type:

dict

Default:

{'light': 'mint', 'dark': 'teal'}

Registered by:

sphinx_config_demo.setup()

demo_show_callouts

config html

config html

demo_show_callouts

Type:

bool

Default:

True

Registered by:

sphinx_config_demo.setup()

---

docutils directives and roles

Directives

.. demobadge::

directive

directive

.. demobadge::

Render a short badge-like paragraph for directive demos.

Options:

Python path:

docutils_demo.DemoBadgeDirective

Required arguments:

1

Optional arguments:

0

Final argument whitespace:

True

Has content:

False

:class:

option

option

:class:

Validator: class_option.

Roles

:demo-badge:

role

role

:demo-badge:

Return a literal node with badge-style classes.

Python path:

docutils_demo.demo_badge_role

Accepts role content:

True

class:

class_option