sphinx-autodoc-api-style

Alpha GitHub PyPI

Sphinx extension that adds type and modifier badges to standard Python domain entries (functions, classes, methods, properties, attributes, data, exceptions). Mirrors the badge system from sphinx-autodoc-pytest-fixtures so API pages and fixture pages share a consistent visual language.

$ pip install sphinx-autodoc-api-style

Features

  • Type badges (rightmost): function, class, method, property, attribute, data, exception — each with a distinct color

  • Modifier badges (left of type): async, classmethod, staticmethod, abstract, final, deprecated

  • Card containers: bordered cards with secondary-background headers

  • Dark mode: full light/dark theming via CSS custom properties

  • Accessibility: keyboard-focusable badges with tooltip popups

  • Non-invasive: hooks into doctree-resolved without replacing directives

How it works

Add sphinx_autodoc_api_style to your Sphinx extensions. With gp-sphinx, use extra_extensions:

conf = merge_sphinx_config(
    project="my-project",
    version="1.0.0",
    copyright="2026, Your Name",
    source_repository="https://github.com/your-org/my-project/",
    extra_extensions=["sphinx_autodoc_api_style"],
)

Or without merge_sphinx_config:

extensions = ["sphinx_autodoc_api_style"]

No special directives are needed — existing .. autofunction::, .. autoclass::, .. automodule:: directives automatically receive badges.

Live demo

Functions

gas_demo_api.demo_function(name, count=1)function

Plain function. Shows function type badge.

Return type:

list[str]

Parameters:

  • name (str) – The name to repeat.

  • count (int) – Number of repetitions.

Returns:

A list of repeated names.

Return type:

list[str]

async gas_demo_api.demo_async_function(url)async function

Asynchronous function. Shows async + function badges.

Return type:

bytes

Parameters:

url (str) – The URL to fetch.

Returns:

The fetched content.

Return type:

bytes

gas_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

gas_demo_api.DEMO_CONSTANT: int = 42data

Module-level constant. Shows data type badge.

Exceptions

exception gas_demo_api.DemoErrorexception

Bases: Exception

Custom exception class. Shows exception type badge.

Raised when a demo operation fails unexpectedly.

Classes

class gas_demo_api.DemoClassclass

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.

Return type:

str

Parameters:

x (int) – Input value.

Returns:

String representation.

Return type:

str

classmethod from_int(n)classmethod method

Class method. Shows classmethod + method badges.

Return type:

DemoClass

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.

Return type:

int

Parameters:

  • a (int) – First operand.

  • b (int) – Second operand.

Returns:

Sum of operands.

Return type:

int

property computed: strproperty

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 gas_demo_api.DemoAbstractBaseclass

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.

Return type:

str

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

Badge reference

Type badges

Object type

CSS class

Color

function

gas-type-function

Blue

class

gas-type-class

Indigo

method

gas-type-method

Cyan

property

gas-type-property

Teal

attribute

gas-type-attribute

Slate

data

gas-type-data

Grey

exception

gas-type-exception

Rose

Modifier badges

Modifier

CSS class

Style

async

gas-mod-async

Purple outlined

classmethod

gas-mod-classmethod

Amber outlined

staticmethod

gas-mod-staticmethod

Grey outlined

abstract

gas-mod-abstract

Indigo outlined

final

gas-mod-final

Emerald outlined

deprecated

gas-deprecated

Red/grey outlined

CSS prefix

All CSS classes use the gas- prefix (gp-sphinx api style) to avoid collision with spf- (sphinx pytest fixtures) or other extensions.

Copyable config snippet

extensions = [
    "sphinx_autodoc_api_style",
]

Package metadata

Registered Surface

sphinx_autodoc_api_style

Source on GitHub · PyPI