# API Dokumentations-Generator (v2)

**Generischer**, konfigurierbarer Generator für MkDocs API-Referenzen mit Auto-Discovery.

## Features

- **Auto-Discovery**: Scannt automatisch Python-Module und erstellt Dokumentation
- **Convention-based**: Verwendet Namenskonventionen für automatische Strukturierung
- **YAML-Konfiguration**: Optionale Overrides für spezielle Anforderungen
- **Package-agnostisch**: Funktioniert mit beliebigen Python-Packages
- **Multi-Class Support**: Gruppiert zusammengehörige Klassen automatisch
- **Exclude-Liste**: Filtert interne Module aus
- **Full-Replace**: Löscht alte Dateien und generiert alles neu

## Schnellstart

### 1. Konfiguration erstellen

Kopiere `api_docs_config.yaml` und passe es an dein Package an:

```yaml
package:
  name: your_package_name
  src_dir: src
  docs_dir: docs/api

auto_discovery:
  enabled: true
  scan_dirs:
    - .
    - operations
    - models
  exclude:
    - internal_module.py
```

### 2. Script ausführen

```bash
# Standard (verwendet scripts/api_docs_config.yaml)
poetry run python scripts/generate_api_docs_v2.py

# Mit custom Config
poetry run python scripts/generate_api_docs_v2.py --config path/to/config.yaml
```

### 3. Dokumentation bauen

```bash
poetry run mkdocs build
```

## Konfiguration

### Package-Section

```yaml
package:
  name: questra_data       # Package-Name (erforderlich)
  src_dir: src             # Pfad zum Source-Verzeichnis
  docs_dir: docs/api       # Pfad zur API-Dokumentation
```

### Auto-Discovery

```yaml
auto_discovery:
  enabled: true

  # Verzeichnisse die gescannt werden
  scan_dirs:
    - .                    # Root-Level (client.py, etc.)
    - operations           # operations/*.py
    - models               # models/*.py

  # Module die ignoriert werden
  exclude:
    - internal_api.py
    - _private_module.py

  # Gruppierung von Models
  grouping:
    models:
      categories:
        - pattern: "inventory|namespace"
          name: "Inventory Models"
          filename: "models-inventory.md"
        - pattern: "timeseries"
          name: "TimeSeries Models"
          filename: "models-timeseries.md"
```

### Overrides

Überschreibe Auto-Discovery für spezielle Fälle:

```yaml
overrides:
  # Einzelne Datei mit Custom-Content
  client.md:
    title: "Custom Title"
    intro: "Custom introduction text"
    usage_example: |
      from mypackage import MyClient
      client = MyClient()
    see_also:
      - title: "Related Doc"
        link: "other.md"

  # Multi-Module Dokument mit Sections
  rest-operations.md:
    title: "REST Operationen"
    intro: "REST API Operations"
    modules:
      - operations/rest_timeseries.py
      - operations/rest_file.py
      - operations/rest_audit.py
    group_sections:
      - title: "TimeSeries Operationen"
        classes: ["TimeSeriesOperations"]
      - title: "File Operationen"
        classes: ["FileOperations"]
      - title: "Audit Operationen"
        classes: ["AuditOperations"]
    heading_level: 3
    usage_example: |
      # Custom example code
```

## Verwendung in anderen Packages

### 1. Script und Config kopieren

```bash
cp scripts/generate_api_docs_v2.py your-project/scripts/
cp scripts/api_docs_config.yaml your-project/scripts/
```

### 2. Config anpassen

```yaml
package:
  name: your_package        # Ändere Package-Name
  src_dir: src
  docs_dir: docs/api

auto_discovery:
  enabled: true
  scan_dirs:
    - .                     # Scanne deine Verzeichnisse
    - your_submodule
  exclude:
    - your_internal_module.py
```

### 3. Ausführen

```bash
cd your-project
poetry run python scripts/generate_api_docs_v2.py
```

## Konventionen

### Auto-Discovery Verhalten

**Root-Level Module** (`scan_dirs: ["."]`)
- `client.py` → `client.md` ("Client")
- `highlevel_client.py` → `highlevel-client.md` ("Highlevel Client")
- Jede Datei wird einzeln dokumentiert

**Operations Module** (`scan_dirs: ["operations"]`)
- `operations/queries.py` → `queries.md` ("Queries")
- `operations/mutations.py` → `mutations.md` ("Mutations")
- Einzeln dokumentiert (außer explizit in Override gruppiert)

**Models Module** (`scan_dirs: ["models"]`)
- Gruppierung nach Config-Pattern
- `models/inventory.py` + `models/namespace.py` → `models-inventory.md`
- Mehrere Module pro Dokument möglich

### Exclude-Patterns

Module werden ignoriert wenn:
- Dateiname in `exclude` Liste ist (`rest_api.py`)
- Private Module (`_internal.py`)
- `__init__.py` Dateien (automatisch)

### Namenskonventionen

- **snake_case Module** → **kebab-case Dateien**: `highlevel_client.py` → `highlevel-client.md`
- **Titel**: Automatisch aus Dateinamen generiert oder via Override
- **Sections**: Bei Multi-Class Docs via `group_sections`

## Ausgabeformat

### Generierte Dateien

| Input | Output | Beschreibung |
|-------|--------|--------------|
| `client.py` | `client.md` | Einzelne Klasse |
| `operations/queries.py` | `queries.md` | Operations Klasse |
| `operations/rest_*.py` (3 files) | `rest-operations.md` | Multi-Class mit Sections |
| `models/inventory.py` + `models/namespace.py` | `models-inventory.md` | Gruppierte Models |

### Markdown-Struktur

```markdown
# Title

Intro text

::: package.module.ClassName
    options:
      show_source: true
      heading_level: 2
      members:
        - method1
        - method2

## Übersicht

Summary from docstring

## Verwendung

```python
# Usage example
```

## Siehe auch

- [Related](link.md)
```

## Erweiterte Features

### Custom Grouping

Models nach beliebigen Patterns gruppieren:

```yaml
grouping:
  models:
    categories:
      - pattern: "user|auth|session"
        name: "Authentication Models"
        filename: "models-auth.md"
      - pattern: "product|order|cart"
        name: "E-Commerce Models"
        filename: "models-ecommerce.md"
```

### Multi-Module Dokumente

Mehrere Module in einem Dokument mit Sections:

```yaml
overrides:
  api-clients.md:
    title: "API Clients"
    modules:
      - http_client.py
      - graphql_client.py
      - rest_client.py
    group_sections:
      - title: "HTTP Client"
        classes: ["HTTPClient"]
      - title: "GraphQL Client"
        classes: ["GraphQLClient"]
```

### Conditional Docs

Nur bestimmte Module dokumentieren:

```yaml
auto_discovery:
  scan_dirs:
    - public_api     # Nur public_api/ scannen
  exclude:
    - internal*      # Alle internal* Module ignorieren
    - _*             # Alle privaten Module ignorieren
```

## Fehlerbehandlung

### Problem: PyYAML nicht gefunden

```bash
[ERROR] PyYAML nicht installiert
```

**Lösung**: Mit `poetry run` ausführen oder PyYAML installieren:

```bash
poetry add pyyaml
# oder
pip install pyyaml
```

### Problem: Config nicht gefunden

```bash
[ERROR] Config nicht gefunden: scripts/api_docs_config.yaml
```

**Lösung**: Prüfe Pfad oder gib explizit an:

```bash
python scripts/generate_api_docs_v2.py --config my_config.yaml
```

### Problem: Keine Module gefunden

```bash
[1/3] Auto-Discovery...
      Gefunden: 0 Module
```

**Lösung**:
- Prüfe `package.name` in Config
- Prüfe `scan_dirs` Pfade
- Prüfe `exclude` Liste

### Problem: Falsche Dateinamen

```bash
[OK] models-permission.md    # Erwartet: models-permissions.md
```

**Lösung**: Nutze `filename` in Kategorie-Config:

```yaml
categories:
  - pattern: "permission|role"
    filename: "models-permissions.md"
```

## Migration von v1

### Unterschiede

| Feature | v1 (generate_api_docs.py) | v2 (generate_api_docs_v2.py) |
|---------|---------------------------|------------------------------|
| Konfiguration | Hart-codiert im Script | YAML-Datei |
| Generizität | Package-spezifisch | Package-agnostisch |
| Erweiterbarkeit | Script-Anpassung nötig | Config-Anpassung ausreichend |
| Exclude-Liste | Keine | Ja |
| Multi-Module Docs | Fest definiert | Konfigurierbar |

### Migration Steps

1. **Erstelle Config**: Kopiere `api_docs_config.yaml`
2. **Passe an**: Ändere Package-Namen und Pfade
3. **Teste**: `poetry run python scripts/generate_api_docs_v2.py`
4. **Vergleiche**: Prüfe generierte Dateien vs. alte
5. **Anpasse**: Füge Overrides für Abweichungen hinzu
6. **Ersetze**: Lösche v1, nutze v2

### Rückwärtskompatibilität

v2 sollte identische Output wie v1 erzeugen (mit korrekter Config). Bei Abweichungen:

1. Prüfe `exclude` Liste
2. Prüfe `grouping.models.categories` Patterns
3. Prüfe `overrides` für spezielle Dokumente

## Best Practices

### 1. Minimale Config

Beginne mit minimaler Config und füge Overrides nur bei Bedarf hinzu:

```yaml
package:
  name: mypackage
  src_dir: src
  docs_dir: docs/api

auto_discovery:
  enabled: true
  scan_dirs: ["."]
```

### 2. Interne Module ausschließen

```yaml
exclude:
  - "*_internal.py"
  - "_*.py"
  - "transport.py"
```

### 3. Logische Gruppierung

Gruppiere Models nach Domänen, nicht nach technischen Details:

```yaml
# Gut
categories:
  - pattern: "user|profile|auth"
    name: "User Management"

# Schlecht
categories:
  - pattern: "dataclass|model"
    name: "All Models"
```

### 4. Dokumentation im Code

Die beste Dokumentation kommt aus guten Docstrings:

```python
class MyClient:
    """
    Client für My API.

    Bietet Methoden für CRUD-Operationen.
    """
```

Auto-Discovery nutzt diese Docstrings für "Übersicht" Sections.

## Performance

- **Scan-Zeit**: ~0.5s für 20 Module
- **AST-Parsing**: ~10ms pro Modul
- **Markdown-Generierung**: <1ms pro Datei
- **Gesamt**: ~1-2s für typisches Package

## Technische Details

- **Python**: 3.10+ (native type hints)
- **Dependencies**: PyYAML (+ Standard Library)
- **AST-basiert**: Kein Import der Module nötig
- **Encoding**: UTF-8
- **Plattform**: Windows/Linux/macOS

## Lizenz

Siehe Projekt-Root LICENSE
