# Docs Generator

The docs generator transforms a `ContractMetadata` object into human-readable documentation. The default output format is Markdown, making it easy to pipe generated docs into static site generators, pull requests, or wikis.

## Classes

::: pycharter.docs_generator.generator.DocsGenerator
    options:
      show_root_heading: true
      heading_level: 3

::: pycharter.docs_generator.renderers.MarkdownRenderer
    options:
      show_root_heading: true
      heading_level: 3

## Quick start

```python
from pycharter import parse_contract_file
from pycharter.docs_generator import DocsGenerator

# Parse a contract
contract = parse_contract_file("contracts/orders.yaml")

# Generate Markdown documentation
generator = DocsGenerator()
docs = generator.generate(contract)
print(docs)
```

## Selective output

Control which sections are included:

```python
docs = generator.generate(
    contract,
    include_schema=True,
    include_coercions=True,
    include_validations=True,
    include_metadata=True,
)
```

## Saving to a file

```python
from pathlib import Path

docs = generator.generate(contract)
Path("docs/contracts/orders.md").write_text(docs)
```

## Generating docs for all contracts

```python
from pathlib import Path
from pycharter import parse_contract_file
from pycharter.docs_generator import DocsGenerator

generator = DocsGenerator()
output_dir = Path("docs/contracts")
output_dir.mkdir(parents=True, exist_ok=True)

for contract_file in Path("contracts").glob("*.yaml"):
    contract = parse_contract_file(str(contract_file))
    docs = generator.generate(contract)
    out = output_dir / f"{contract_file.stem}.md"
    out.write_text(docs)
    print(f"Generated {out}")
```

## Custom renderer

Implement `DocsRenderer` to produce HTML, RST, or any other format:

```python
from pycharter.docs_generator.renderers import DocsRenderer
from pycharter.docs_generator import DocsGenerator

class HtmlRenderer(DocsRenderer):
    def render_header(self, title: str, version: str | None) -> str:
        ver = f" <small>v{version}</small>" if version else ""
        return f"<h1>{title}{ver}</h1>"

    def render_description(self, description: str) -> str:
        return f"<p>{description}</p>"

    # ... implement remaining methods

generator = DocsGenerator(renderer=HtmlRenderer())
html = generator.generate(contract)
```

## REST API

Generate documentation for a stored contract via the REST API:

```bash
curl http://localhost:8000/api/v1/contracts/{contract_id}/docs
```

The response is a Markdown string.

## Import

```python
from pycharter.docs_generator import DocsGenerator
from pycharter.docs_generator.renderers import MarkdownRenderer, DocsRenderer
```

## See also

- [Contract Parser](contract-parser.md)
- [Data Contracts & Validation tutorial](../tutorials/contracts-validation.md)
