Docstring Style Guide

We use Google-style docstrings. Type annotations live in the code — don't repeat them in docstrings.

Functions and Methods

def mkfs(device: str | Path, fs_type: str, *, force: bool = False) -> bool:
    """Create filesystem on device.

    Args:
        device: Block device to format.
        fs_type: Filesystem type (ext4, xfs, …).
        force: Overwrite existing filesystem.

    Returns:
        True on success.

    Example:
        ```python
        mkfs('/dev/sda1', 'ext4', force=True)
        ```
    """

Pydantic Model Classes

Use Attributes: (not Args:) to document fields — griffe maps Args: to the function signature and will warn when the names don't match.

class LogicalVolume(LvmDevice):
    """Logical Volume device.

    Attributes:
        vg: Parent volume group.
        pool_name: Thin pool (if thin LV).

    Example:
        ```python
        lv = LogicalVolume(name='lv0', vg='vg0')
        ```
    """

    vg: str | None = None
    pool_name: str | None = None

Formatting and Preview

uv run ruff format          # formats code in docstrings too
uv run mkdocs serve         # preview at http://127.0.0.1:8000