"""
Renderer-agnostic Python documentation compiler that converts docstrings into
structured documentation for both humans (MkDocs) and machines (MCP / AI agents).

`doc-forge` statically analyzes your source code, builds a semantic model of
modules and objects, and renders that model into documentation outputs without
executing your code.

---

## Core Philosophy

`doc-forge` follows a compiler architecture:

1. **Front-end (Introspection)**
   Static analysis of modules, classes, functions, signatures, and docstrings.

2. **Middle-end (Semantic Model)**
   Renderer-neutral structured representation of your API.

3. **Back-end (Renderers)**

   * MkDocs → human documentation
   * MCP JSON → AI-readable documentation

The atomic unit of documentation is the Python import path.

Example:

```python
from my_package.foo import Bar
```

---

## Docstring Writing Standard

Docstrings are the single source of truth. `doc-forge` does not generate content.
It compiles and renders what you write.

Documentation follows the Python import hierarchy.

---

## Package docstring (`package/__init__.py`) — Full user guide

This is the landing page. A developer must be able to install and use the
package after reading only this docstring.

Example:

```python
'''
my_package

Short description of what this package provides.

## Installation

pip install my-package

## Quick start

from my_package.foo import Bar

bar = Bar()
result = bar.process("example")

## Core concepts

Bar
    Primary object exposed by the package.

foo module
    Provides core functionality.

## Typical workflow

1. Import public objects
2. Initialize objects
3. Call methods

## Public API

foo.Bar
foo.helper_function
'''
```

---

## Submodule docstring (`package/foo/__init__.py`) — Subsystem guide

Explains a specific subsystem.

Example:

```python
'''
foo subsystem.

Provides core functionality.

## Usage

from my_package.foo import Bar

bar = Bar()
bar.process("example")
'''
```

---

## Class docstring — Object contract

Defines responsibility and behavior.

Example:

```python
class Bar:
    '''
    Performs processing on input data.

    Instances may be reused across multiple calls.
    '''
```

Include:

* Responsibility
* Lifecycle expectations
* Thread safety (if relevant)
* Performance characteristics (if relevant)

---

## Function and method docstrings — API specification

Example:

```python
def process(self, value: str) -> str:
    '''
    Process an input value.

    Args:
        value:
            Input string.

    Returns:
        Processed string.

    Raises:
        ValueError:
            If the input is invalid.
    '''
```

---

## Attribute docstrings (optional)

Example:

```python
self.name: str
'''Identifier used during processing.'''
```

---

## Writing Rules

**Required**

* Use Markdown headings
* Provide real import examples
* Document all public APIs
* Keep descriptions precise and factual

**Avoid**

* Plain-text separators like `====`
* Duplicate external documentation
* Informal or conversational language

---

## How doc-forge uses these docstrings

Build MkDocs site:

```bash
doc-forge build --mkdocs --module my_package
```

Build MCP documentation:

```bash
doc-forge build --mcp --module my_package
```

Both outputs are generated directly from docstrings.
"""

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",
]