"""
Renderer base interfaces and configuration models.

This module defines the base protocol and configuration container used by
doc-forge renderers. Concrete renderer implementations should implement the
``DocRenderer`` protocol.
"""

from pathlib import Path
from typing import Protocol

from docforge.models import Project


class RendererConfig:
    """
    Configuration container for documentation renderers.

    A ``RendererConfig`` instance groups together the project model and the
    output directory used during rendering.

    Attributes:
        out_dir: Directory where generated documentation files will be written.
        project: Documentation project model to be rendered.
    """

    def __init__(self, out_dir: Path, project: Project) -> None:
        """
        Initialize a RendererConfig instance.

        Args:
            out_dir: Target directory where documentation files should be written.
            project: Introspected project model to render.
        """
        self.out_dir = out_dir
        self.project = project


class DocRenderer(Protocol):
    """
    Protocol defining the interface for documentation renderers.

    Implementations of this protocol are responsible for transforming a
    ``Project`` model into renderer-specific documentation sources.
    """

    name: str

    def generate_sources(
        self,
        project: Project,
        out_dir: Path,
    ) -> None:
        """
        Generate renderer-specific documentation sources.

        Args:
            project: Project model containing modules and documentation objects.
            out_dir: Directory where generated documentation sources
                should be written.
        """
        ...