"""
# doc-forge

`doc-forge` is a renderer-agnostic Python documentation compiler designed for
speed, flexibility, and beautiful output. It decouples the introspection of
your code from the rendering process, allowing you to generate documentation
for various platforms (starting with MkDocs) from a single internal models.

## Core Philosophy

`doc-forge` operates on two fundamental principles:

1.  **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.
2.  **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:
    -   **Front-end (Introspection)**: Static analysis of source code and docstrings.
    -   **Middle-end (Semantic Model)**: A renderer-neutral internal representation.
    -   **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.

## Documentation Design

`doc-forge` is an "AI-Native" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:

### For Humans (Readability & Structure)
- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.
- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.
- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.

### For LLMs (AI-Native Knowledge)
- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to "understand" your API surface area without layout noise.
- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.
- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.
## Available Commands

- **build**: Build documentation (MkDocs site or MCP resources).
- **serve**: Serve documentation (MkDocs or MCP).
- **tree**: Visualize the introspected project structure.

## Installation

Install using `pip` with the optional `mkdocs` dependencies for a complete setup:

```bash
pip install doc-forge
```

## Quick Start

1.  **Build Documentation**:
    Introspect your package and generate documentation in one step:
    ```bash
    # Build MkDocs site
    doc-forge build --mkdocs --module my_package --site-name "My Docs"

    # Build MCP resources
    doc-forge build --mcp --module my_package
    ```

2.  **Define Navigation**:
    Create a `docforge.nav.yml` to organize your documentation:
    ```yaml
    home: my_package/index.md
    groups:
      Core API:
        - my_package/core/*.md
      Utilities:
        - my_package/utils.md
    ```

3.  **Preview**:
    ```bash
    # Serve MkDocs site
    doc-forge serve --mkdocs

    # Serve MCP documentation
    doc-forge serve --mcp
    ```

## Project Structure

- `docforge.loaders`: Introspects source code using static analysis (`griffe`).
- `docforge.models`: The internal representation of your project, modules, and objects.
- `docforge.renderers`: Converters that turn the models into physical files.
- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
"""

from .loaders import GriffeLoader, discover_module_paths
from .renderers import MkDocsRenderer, MCPRenderer
from .cli import main
from . import models

__all__ = [
    "GriffeLoader",
    "discover_module_paths",
    "MkDocsRenderer",
    "MCPRenderer",
    "models",
    "main",
]