core

Doxs core library - YAML-first flavour.

Turns YAML-formatted docstrings into enriched numpydoc sections.

Example

@doxs  # or simply ``@doxs`` if you re-export apply at top level
def add(x: int, y: int) -> int:
    """
    title: Return the sum of two integers
    summary: |
        This function returns the sum of two integer numbers.
    parameters:  # noqa
        x: The first operand
        y: The second operand
    returns: Sum of *x* and *y*
    """
    return x + y

The decorator will append a numpydoc block like:

Return the sum of two integers.

This function returns the sum of two integer numbers.

Parameters
----------
x : int, default is `…`
    The first operand
...

Classes:

• DocString –

  Carry a description inside typing.Annotated metadata.

Functions:

• apply –

  Decorate a class or callable and convert YAML → numpydoc.

DocString dataclass

DocString(description: str)

Carry a description inside typing.Annotated metadata.

apply

apply(
    _obj: Any = None,
    *,
    class_vars: Optional[Dict[str, str]] = None,
    params: Optional[Dict[str, str]] = None,
    returns: Optional[Union[str, List[str]]] = None,
) -> Any

Decorate a class or callable and convert YAML → numpydoc.

Source code in src/doxs/core.py

def apply(
    _obj: Any = None,
    *,
    class_vars: Optional[Dict[str, str]] = None,
    params: Optional[Dict[str, str]] = None,
    returns: Optional[Union[str, List[str]]] = None,
) -> Any:
    """Decorate a class or callable and convert YAML → numpydoc."""

    def decorator(obj: Any) -> Any:
        if inspect.isclass(obj):
            return _decorate_class(obj, class_vars or {})
        if callable(obj):
            return _decorate_func(obj, params or {}, returns)
        return obj

    return decorator if _obj is None else decorator(_obj)