sphinx-ux-autodoc-layout

Alpha GitHub PyPI

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.

Wraps contiguous desc_content runs into semantic api_region nodes and rebuilds Python autodoc entries into stable api-* components. Large field-list parameter sections still use native <details>/<summary>, while inline signature expansion uses a custom disclosure that reveals Sphinx’s native multiline parameter-list rendering.

It is now the shared presenter for the whole autodoc family. desc-backed entries use it directly, and section-card consumers reuse the same inner shell through the public build_api_card_entry() helper.

$ pip install sphinx-ux-autodoc-layout

Pipeline position

Hooks doctree-resolved at priority 600, after sphinx-autodoc-api-style at 500. Consumes the api_slot nodes that producer packages inject into desc_signature during earlier transforms, and composes them into the final gp-sphinx-api-layout-right subcomponent (badges, source link, permalink).

The extension also overrides Sphinx’s built-in desc_signature HTML visitor (app.add_node(addnodes.desc_signature, override=True, ...)). This is a deliberate platform decision: taking ownership of signature rendering allows the gp-sphinx-api-link permalink to be placed inside the managed layout rather than appended by Sphinx’s default handler.

Event

Hook

Priority

doctree-resolved

on_doctree_resolved

600 (after api-style at 500)

object-description-transform

—

not used

Downstream conf.py

With gp-sphinx:

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_ux_autodoc_layout"],
    api_layout_enabled=True,
    api_collapsed_threshold=10,
)

Or without merge_sphinx_config:

extensions = ["sphinx.ext.autodoc", "sphinx_ux_autodoc_layout"]
api_layout_enabled = True

Working usage examples

Render one compact function:

```{eval-rst}
.. autofunction:: my_project.api.compact_function
```

Render a class with grouped content regions and member entries:

```{eval-rst}
.. autoclass:: my_project.api.LayoutDemo
   :members:
```

Live demos

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__
method
Parameters (14)
Parameters:
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

The class above renders with:

  • narrative region (class docstring)

  • fields region with fold (13 parameters > threshold of 10)

  • members region (connect, execute, close methods)

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

Configuration

Setting

Default

Meaning

api_layout_enabled

False

Enables the transform

api_fold_parameters

True

Folds large field-list sections

api_collapsed_threshold

10

Minimum field count before folding

api_signature_show_annotations

True

Shows name: type in expanded folded signatures when type data is available

Shared helper surface

  • build_api_card_entry() builds the shared inner api-* shell for section-card consumers such as FastMCP.

  • build_api_summary_section() wraps summary and index tables in the shared gp-sphinx-api-summary region.

CSS classes

Class

Element

Purpose

gp-sphinx-api-container

<dl>

Managed autodoc shell

gp-sphinx-api-header

<dt>

Signature row shell

gp-sphinx-api-content

<dd>

Description/content shell

gp-sphinx-api-layout

<div>

Header split between left and right

gp-sphinx-api-layout-left

<div>

Signature text, custom disclosure, permalink

gp-sphinx-api-layout-right

<div>

Badge container and source link

gp-sphinx-api-signature

<div>

Compact signature row

gp-sphinx-api-link

<a>

Managed permalink in the left layout

gp-sphinx-api-badge-container

<span>

Wrapper for badge group output

gp-sphinx-api-source-link

<span>

Wrapper for the [source] link

gp-sphinx-api-description

<div>

Wraps paragraphs, notes, examples

gp-sphinx-api-parameters

<div>

Wraps field lists (Parameters, Returns)

gp-sphinx-api-footer

<div>

Wraps nested method/attribute entries

gp-sphinx-api-region

<div>

Compatibility alias on content sections

gp-sphinx-api-region--narrative

<div>

Compatibility alias on narrative sections

gp-sphinx-api-region--fields

<div>

Compatibility alias on parameter sections

gp-sphinx-api-region--members

<div>

Compatibility alias on footer/member sections

gp-sphinx-api-fold

<details>

Disclosure wrapper for large sections

gp-sphinx-api-fold-summary

<summary>

Click target showing field count

API reference

sphinx_ux_autodoc_layout.build_api_card_entry(*, profile_class, signature_children, content_children=(), badge_group=None, permalink=None, entry_classes=(), signature_classes=(), content_classes=())
function

Build a shared gp-sphinx-api-* card entry for non-desc consumers.

Parameters (10)
Parameters:

  • profile_class (str) – Stable profile class such as "gp-sphinx-api-profile--fastmcp-tool".

  • signature_children (Sequence[nodes.Node]) – Children placed inside the gp-sphinx-api-signature wrapper.

  • content_children (Sequence[nodes.Node]) – Children appended to gp-sphinx-api-content.

  • badge_group (nodes.Node | None) – Shared badge group rendered inside gp-sphinx-api-badge-container.

  • permalink (api_permalink | None) – Explicit header permalink placed in gp-sphinx-api-layout-left.

  • entry_classes (tuple[str, ...]) – Extra CSS classes for the outer gp-sphinx-api-entry wrapper.

  • signature_classes (tuple[str, ...]) – Extra classes for the gp-sphinx-api-signature wrapper.

  • content_classes (tuple[str, ...]) – Extra classes for the gp-sphinx-api-content wrapper.

Returns:

Shared card entry tree using the stable gp-sphinx-api-* contract.

Return type:

nodes.Element

sphinx_ux_autodoc_layout.build_api_summary_section(*children, classes=())
function

Wrap summary or index content in the shared gp-sphinx-api-summary region.

Parameters:

  • *children (nodes.Node) – Summary or index nodes to render in the shared summary region.

  • classes (tuple[str, ...]) – Extra CSS classes appended to the summary wrapper.

Returns:

Shared summary wrapper.

Return type:

api_component

Examples

>>> from docutils import nodes
>>> section = build_api_summary_section(nodes.paragraph("", "Summary"))
>>> section.get("name")
'gp-sphinx-api-summary'
sphinx_ux_autodoc_layout.build_api_table_section(name, *children, classes=())
function

Wrap one or more table-like body nodes in a shared API section.

Parameters:
Return type:

api_component

sphinx_ux_autodoc_layout.build_api_facts_section(rows, *, classes=())
function

Render a shared gp-sphinx-api-facts section from typed fact rows.

Parameters:
Return type:

api_component

Copyable config snippet

extensions = [
    "sphinx_ux_autodoc_layout",
]

Registered Surface

sphinx_ux_autodoc_layout

Config values

Name

Default

Rebuild

Types

api_layout_enabled

False

env

bool

api_fold_parameters

True

env

bool

api_collapsed_threshold

10

env

int

api_signature_show_annotations

True

env

bool