quirl.components.documentor

Assembles complete documentation for any Duck component.

Module Contents

Classes

Documentor

Stitches together full documentation for any Duck component.

Data

TYPE_ANNOTATION_PATTERN

API

class quirl.components.documentor.Documentor(element: Optional[str] = None, properties: Optional[Dict[str, str]] = None, props: Optional[Dict[str, str]] = None, style: Optional[Dict[str, str]] = None, inner_html: Optional[Union[str, str, float]] = None, children: Optional[List[duck.html.components.HtmlComponent]] = None, **kwargs)[source]

Bases: duck.html.components.container.Container

Stitches together full documentation for any Duck component.

Combines the docstring description, a props reference, a usage code block, and an animated live preview into a single styled documentation card.

Required Props:

  • component_cls: The component class to document. Required.

Optional Props:

  • title: Optional heading text. Defaults to the class name.

  • id: Stable DOM id for the documentation card.

Initialization

Initialize an HTML component.

Parameters:

  • element – The HTML element tag name (e.g., textarea, input, button). Can be None, but make sure element is returned by get_element method.

  • accept_inner_html – Whether the HTML component accepts an inner body (e.g., inner-body-here).

  • inner_html – Inner html to add to the HTML component. Defaults to None.

  • properties – Dictionary for properties to initialize the component with.

  • props – Just same as properties argument (added for simplicity).

  • style – Dictionary for style to initialize the component with.

  • event_handlers – Events to automatically bind. Each dictionary maps an event name to its handler and may include additional keyword arguments forwarded to bind(), e.g. event_handlers=[{"click": on_button_click, **extra_kwargs}].

  • **kwargs – Extra keyword arguments

Raises:

HtmlComponentError – If ‘element’ is not a string or ‘inner_html’ is set but ‘accept_inner_html’ is False.

build_description() → duck.html.components.paragraph.Paragraph[source]

Return the first paragraph of the docstring as a description.

Returns:

A Paragraph with the description text, or an empty Paragraph if no docstring is present.

build_header() → duck.html.components.container.Container[source]

Build the component name heading with a category badge.

Returns:

A Container with the title and a small “Component” badge.

build_no_preview_placeholder() → duck.html.components.container.Container[source]

Build the placeholder shown when a component opts out of a preview.

Returns:

A dashed-border Container explaining the lack of a preview.

build_preview_section()[source]

Build the live preview with animated demo, or a placeholder.

A component opts out of a preview by setting the class attribute docs_preview_kwargs = None (as opposed to {}, which means “no kwargs needed but a preview is still wanted”). Optionally set docs_no_preview_reason for a specific explanation.

Returns:

A Demo component with the live preview and animation, or a Container explaining why no preview is available.

build_prop_group(label: str, props: list, badge_variant: str) → duck.html.components.container.Container[source]

Build a single labeled group of prop rows.

Parameters:

  • label – Section heading text, e.g. “Required Props”.

  • props – List of raw “name: description” prop lines.

  • badge_variant – Badge variant used for the section label.

Returns:

A Container with the section heading and prop rows.

build_prop_row(prop_text: str) → duck.html.components.container.Container[source]

Build a single prop row with the name emphasized as code.

Supports an optional type annotation in the name, formatted as key (type): description.

Parameters:

prop_text – Raw “name: description” text from the docstring.

Returns:

A Container styled as a row inside a props list.

build_props_section() → duck.html.components.container.Container[source]

Parse Required Props and Optional Props from the docstring.

Supports typed prop names (e.g. key (str): ...) and multi-line descriptions, where continuation lines are indented under the prop and a blank line separates one prop from the next.

Returns:

A Container with headings and prop rows for each section found in the docstring.

build_usage_section() → duck.html.components.container.Container[source]

Build the Usage code block from the same kwargs driving the Demo.

Sourcing usage from docs_preview_kwargs (rather than a hand-written docstring snippet) guarantees the code shown here always matches what the live preview actually renders. Falls back to parsing a ```python block from the docstring only for components that opt out of a preview entirely.

Returns:

A Container with a heading and code block, or an empty Container if there’s nothing to show.

docs_no_preview_reason

“Documentor requires a component_cls to document and isn’t meant to preview itself.”

docs_preview_kwargs

None

extract_docstring_usage() → str[source]

Extract a ```python code block from the docstring.

Only used as a fallback for components with no preview kwargs to generate usage from.

Returns:

The extracted code, or an empty string if none is found.

format_usage_code(kwargs: dict) → str[source]

Render a constructor call string from the exact kwargs used to build the live preview.

Parameters:

kwargs – The component’s docs_preview_kwargs.

Returns:

A Python-formatted constructor call, e.g. Badge(text='Beta').

on_create()[source]

Build the documentation card from the component’s docstring.

quirl.components.documentor.TYPE_ANNOTATION_PATTERN

‘compile(…)’