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

# 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:

    '''
    Short description of what this package provides.

    # Installation

    ```bash
    pip install my-package
    ```

    # Quick start

    ```python
    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:

    '''
    Provides core functionality.

    # Usage

    ```python
    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,
    value1: str,
    value2: str | None = "default value",
    value3: str | None = None,
) -> str:
    '''
    Process an input value.
    ---

    Parameters
    ----------
    value1 : str
        required: True
        value to be processed
        Example:
            'string'

    value2 : str
        required: False
        default: "default value"
        value to be processed
        Example:
            'string'

    value3 : str
        required: False
        value to be processed
        Example:
            'string'
    ---

    Returns
    -------
    processed value : str
        result after processing value
    ---

    Behavior
    --------
    - behaviour 1
    - behaviour 2
    ---
    '''
```
---

# Attribute docstrings (optional)

## Example:

```python
class Class
    '''
    attribute1 : str
        required: True
        default: "default value"
        attribute description

    attribute2 : str
        required: False
        attribute description

    attribute2 : str
        required: False
        default: "default value"
        attribute description
    '''

    attribute1: str = "default value"
    attribute2: str | None = None
    attribute3: str | None = "default value"
```
---

# Writing Rules

**Heading hierarchy**

Module docstring

- Examples
- Usage
- Core concepts
- Public API

Class docstring

- Attributes
- Execution contract
- Lifecycle
- Thread safety
- Notes

Method docstring

- Parameters
- Returns
- Raises
- Yields
- Behavior

**Required**

* Use Markdown headings
* Use Markdown line separator `---`
* Line separator should be followed by a blank line
* 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",
]