Skip to content

Python Documentation Style 📚

Maraudarr documentation should explain contracts and intent without duplicating the implementation. Type annotations remain the source of truth for types; docstrings describe meaning, side effects, invariants, and failure behavior.

Public APIs

Public modules, classes, methods, and functions use Google-style sections when they add useful information:

def write_stack(
    catalog: Catalog,
    plan: StackPlan,
    output_dir: Path,
) -> tuple[Path, Path, Path]:
    """Generate and validate a complete Plundarr project.

    Args:
        catalog: Validated catalog providing templates and service sources.
        plan: Deterministically ordered service selection to generate.
        output_dir: Directory that receives the generated project.

    Returns:
        Paths to the Compose file, environment file, and config directory.

    Raises:
        RenderError: If Docker Compose rejects the staged project.
        OSError: If an output file cannot be written or replaced.
    """

Use Args, Returns, Raises, Attributes, or Note only when applicable. Do not add an empty section, restate a parameter name as its description, or repeat a type already expressed by the signature.

Private Helpers

Private helpers are filtered out of the generated API reference, but they are not undocumented. Give every non-obvious helper a concise docstring that states its transformation or safety rule. Add inline comments at decision points where the reason cannot be inferred from the code.

Good private-helper documentation explains matters such as:

  • Why a marker-based text edit is safe for the owned template shape.
  • Why one environment variable remains generator-owned.
  • Why config README files may refresh while application files may not.
  • Why validation tolerates a missing Docker executable but rejects bad Compose.

Avoid comments that merely translate the following expression into English.

Generated Reference Boundary

The MkDocs configuration renders names that do not begin with _. This keeps the published reference focused on reusable interfaces while source links and the architecture guide preserve visibility into implementation details.

Run make docs after changing Python signatures or docstrings. Strict mode treats malformed cross-references, invalid navigation, and documentation warnings as build failures.