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

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

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

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

Module-level constant. Shows data type badge.

Exceptions

exception gp_demo_api.DemoError

exception

Bases: Exception

Custom exception class. Shows exception type badge.

Raised when a demo operation fails unexpectedly.

Classes

class gp_demo_api.DemoClass

class

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

Class attribute. Shows attribute type badge.

__init__(value)

method

Parameters:

value (str)

Return type:

None

regular_method(x)

method

Regular instance method. Shows method type badge.

Parameters:

x (int) – Input value.

Returns:

String representation.

Return type:

str

classmethod from_int(n)

classmethod method

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

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

Computed property. Shows property type badge.

Returns:

The uppercased value.

Return type:

str

async async_method()

async method

Asynchronous method. Shows async + method badges.

Return type:

None

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

Bases: ABC

Abstract base class. Shows class type badge.

Subclass this to provide concrete implementations.

abstractmethod must_implement()

abstract method

Abstract method. Shows abstract + method badges.

Returns:

Implementation-specific value.

Return type:

str

_abc_impl = <_abc._abc_data object>

attribute

abstractmethod async async_abstract()

abstract async method

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

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

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

Open a connection to the server.

Returns:

True if connection succeeded.

Return type:

bool

execute(query, params=None)

method

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

Close the connection.

Return type:

None

Small function (no fold)

api_demo_layout.compact_function(name, value=0)

function

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

List active sessions for one server.

Returns:

list[str]

create_session

create_session

mutating tool

Create one session and return the created record.

Returns:

dict[str, str | int | bool]

delete_session

delete_session

destructive tool

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 index

Fixture	Flags	Returns	Description
demo_autouse	auto fixture	None	Autouse fixture.
demo_class	class fixture	str	Class-scoped resource.
demo_deprecated	fixture	str	Return a value (deprecated since 1.0, replaced by demo_plain).
demo_factory	factory fixture	type[str]	Return a callable (factory kind).
demo_module	module fixture	str	Module-scoped resource.
demo_override_hook	fixture	str	Override hook — customise in conftest.py.
demo_plain	fixture	str	Plain function-scope resource.
demo_session	session fixture	str	Session-scoped resource.
demo_session_autouse	session auto fixture	None	Session-scoped autouse.
demo_session_factory	session factory fixture	type[str]	Session-scoped factory.

Fixture reference

fixture spf_demo_fixtures.demo_plain → str

fixture

Plain function-scope resource. Shows FIXTURE badge only.

fixture spf_demo_fixtures.demo_session → str

session fixture

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-scoped resource. Shows MODULE + FIXTURE badges.

fixture spf_demo_fixtures.demo_class → str

class fixture

Class-scoped resource. Shows CLASS + FIXTURE badges.

fixture spf_demo_fixtures.demo_factory → type[str]

factory fixture

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

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

fixture spf_demo_fixtures.demo_autouse → None

auto fixture

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

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

Config Value Index

Name	Type	Default	Rebuild
demo_theme_accent	dict	{'light': 'mint', 'dark': 'teal'}	html
demo_show_callouts	bool	True	html

demo_theme_accent

config html

Type:

dict

Default:

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

Registered by:

sphinx_config_demo.setup()

demo_show_callouts

config html

Type:

bool

Default:

True

Registered by:

sphinx_config_demo.setup()

---

docutils directives and roles

Directives

Directive Index

Name	Python path	Summary
demobadge	docutils_demo.DemoBadgeDirective	Render a short badge-like paragraph for directive demos.
democallout	docutils_demo.DemoCalloutDirective	Render a simple titled container for directive demos.

.. demobadge::

directive

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

Validator: class_option.

Roles

Role Index

Name	Python path	Summary
demo-badge	docutils_demo.demo_badge_role	Return a literal node with badge-style classes.

:demo-badge:

role

Return a literal node with badge-style classes.

Python path:

docutils_demo.demo_badge_role

Accepts role content:

True

class:

class_option