API Reference

This page is generated automatically from your code's docstrings by mkdocstrings. At build time it imports the listed modules, reads their docstrings, and renders typed, cross-linked API docs — so the reference never drifts from the code as long as your docstrings are accurate. This project configures the Google docstring style (docstring_style: google in mkdocs.yaml).

Writing docstrings mkdocstrings can render

Write Google-style docstrings — a one-line summary, then Args: / Returns: / Raises: sections. mkdocstrings parses these into structured API docs:

class Repeat(Transform):
    """Repeats the text a fixed number of times.

    Args:
        times: How many space-separated copies to emit.

    Returns:
        The input repeated ``times`` times, joined by spaces.
    """

    def __init__(self, times: int = 2) -> None:
        self.times = times

Type hints are picked up automatically, so you don't repeat types in the docstring.

Documenting a new module

Add a mkdocstrings identifier block — three colons followed by the dotted import path — anywhere on a docs page. This page already documents the example module:

::: cafl4ds.pipeline
    options:
      show_root_heading: true   # render a heading for the module/class
      show_source: true         # include a collapsible "source" view
      docstring_style: google

To document another module, add another block (e.g. ::: cafl4ds.cli) on this page or any other, and list that page in the nav: of mkdocs.yaml.

The live reference for the shipped example module follows:

cafl4ds.pipeline

An example module: a tiny text-transform pipeline.

This is throwaway "replace-me" starter code. It exists to show how the project is wired together -- in particular how Hydra's instantiate builds a nested object graph from config: a Pipeline whose steps are themselves _target_ objects (see configs/pipeline.yaml). Delete it and drop in your own package code.

Pipeline dataclass

Runs an ordered list of transforms over a starting message.

Source code in cafl4ds/pipeline.py

@dataclass
class Pipeline:
    """Runs an ordered list of transforms over a starting message."""

    steps: list[Transform]
    message: str = "hello"

    def run(self) -> str:
        """Apply each transform in turn, log the result, and return it."""
        result = self.message
        for step in self.steps:
            result = step(result)
        logger.info(result)
        return result

run()

Apply each transform in turn, log the result, and return it.

Source code in cafl4ds/pipeline.py

def run(self) -> str:
    """Apply each transform in turn, log the result, and return it."""
    result = self.message
    for step in self.steps:
        result = step(result)
    logger.info(result)
    return result

Repeat

Bases: Transform

Repeats the text times times, space-separated.

Source code in cafl4ds/pipeline.py

class Repeat(Transform):
    """Repeats the text ``times`` times, space-separated."""

    def __init__(self, times: int = 2) -> None:
        """Store how many times to repeat the text."""
        self.times = times

    def __call__(self, text: str) -> str:
        """Return ``text`` repeated ``times`` times, space-separated."""
        return " ".join([text] * self.times)

__call__(text)

Return text repeated times times, space-separated.

Source code in cafl4ds/pipeline.py

def __call__(self, text: str) -> str:
    """Return ``text`` repeated ``times`` times, space-separated."""
    return " ".join([text] * self.times)

__init__(times=2)

Store how many times to repeat the text.

Source code in cafl4ds/pipeline.py

def __init__(self, times: int = 2) -> None:
    """Store how many times to repeat the text."""
    self.times = times

Transform

Bases: ABC

A single pipeline step that maps a string to a string.

Source code in cafl4ds/pipeline.py

class Transform(ABC):
    """A single pipeline step that maps a string to a string."""

    @abstractmethod
    def __call__(self, text: str) -> str:
        """Apply the transform to ``text`` and return the result."""

__call__(text) abstractmethod

Apply the transform to text and return the result.

Source code in cafl4ds/pipeline.py

@abstractmethod
def __call__(self, text: str) -> str:
    """Apply the transform to ``text`` and return the result."""

Upper

Bases: Transform

Upper-cases the text.

Source code in cafl4ds/pipeline.py

class Upper(Transform):
    """Upper-cases the text."""

    def __call__(self, text: str) -> str:
        """Return ``text`` upper-cased."""
        return text.upper()

__call__(text)

Return text upper-cased.

Source code in cafl4ds/pipeline.py

def __call__(self, text: str) -> str:
    """Return ``text`` upper-cased."""
    return text.upper()

If your API docs don't appear

mkdocstrings has to import the module to introspect it, so a missing block usually means an import problem. Check that: the dotted path is correct (cafl4ds.module, not a file path); the package is installed in the docs environment (uv sync before uv run poe docs); and the module imports cleanly on its own. Build with uv run poe docs --verbose to see mkdocstrings' import errors. See the mkdocstrings docs for the full option list.