"""
# Summary

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 (Path):
            Directory where generated documentation files will be written.

        project (Project):
            Documentation project model to be rendered.
    """

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

        Args:
            out_dir (Path):
                Target directory where documentation files should be written.

            project (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):
                Project model containing modules and documentation objects.

            out_dir (Path):
                Directory where generated documentation sources should be written.
        """
        ...