# Scripts

Automatisierungsskripte für Wartungsaufgaben im Questra Umbrella Package.

## Übersicht

| Script | Zweck | Wann ausführen |
|--------|-------|----------------|
| [update_versions.py](update_versions.py) | Aktualisiert Versionsnummern in Dokumentation | Automatisch bei MkDocs Build |
| [sync_docs.py](sync_docs.py) | Synchronisiert API-Dokumentation aus Submodulen | Nach Submodule-Update |
| [check_exports.py](check_exports.py) | Prüft Python Re-Exports im Umbrella Package | Nach Submodule-Update |

## sync_docs.py

### Zweck

Kopiert API-Dokumentationsdateien aus den Submodulen (`data/docs/`, `authentication/docs/`)
in das Haupt-Dokumentationsverzeichnis (`docs/`) und validiert dass alle synchronisierten
Dateien in der `mkdocs.yml` nav-Section referenziert sind.

### Verwendung

```bash
uv run python scripts/sync_docs.py
```

### Wann ausführen

- Nach `git submodule update` wenn neue/geänderte `.md`-Dateien in Submodulen hinzugekommen sind
- Manuell wenn Submodule-Dokumentation sich geändert hat

### Beispiel-Output

**Erfolgreiche Synchronisierung:**

```text
Synced: data/api/client.md
Synced: data/api/managers.md
Synced: data/api/results.md
...
Synced 11 file(s) for data
Synced 4 file(s) for authentication

[OK] All synced files are referenced in mkdocs.yml
```

**Mit fehlenden nav-Einträgen:**

```text
Synced 11 file(s) for data
...

[!] Warning: The following synced files are NOT in mkdocs.yml:
======================================================================
   - data/api/new-feature.md

Consider adding them to the 'nav' section in mkdocs.yml
```

### Nacharbeit bei fehlenden nav-Einträgen

Falls Dateien nicht in `mkdocs.yml` referenziert sind:

1. `mkdocs.yml` öffnen
2. Fehlende Dateien zur `nav:`-Section hinzufügen
3. Pfade müssen relativ zu `docs/` sein (z.B. `data/api/results.md`)

## check_exports.py

### Zweck

Vergleicht `__all__` Exports aus Submodulen mit den Re-Exports im Umbrella Package
(`src/questra/__init__.py`) und zeigt Diskrepanzen an.

### Verwendung

```bash
python scripts/check_exports.py
```

### Output

Das Script zeigt:
- **Missing in umbrella**: Klassen die im Submodule exportiert sind, aber nicht im Umbrella Package
- **Extra in umbrella**: Klassen die im Umbrella importiert sind, aber nicht mehr im Submodule existieren

### Beispiel-Output

```
[!] Found 1 submodule(s) with export differences:

======================================================================
Submodule: questra_data
======================================================================

[!] Missing in umbrella (exported by questra_data):
   - QueryResult
   - TimeSeriesResult
   - BoolProperty
   ...

======================================================================
Review these differences and update src/questra/__init__.py manually.
```

### Manuelle Nacharbeit

Das Script **ändert keine Dateien automatisch**. Entwickler müssen:

1. **Entscheiden** ob fehlende Exports public API werden sollen:
   - Ja → `src/questra/__init__.py` erweitern
   - Nein → Internes API, nichts tun

2. **Prüfen** ob "extra" Exports deprecated sind:
   - Ja → Aus `src/questra/__init__.py` entfernen
   - Nein → False Positive (z.B. unterschiedliche Module)

3. **Versionierung** beachten:
   - Neue Exports = Minor Version Bump (neue Features)
   - Entfernte Exports = Major Version Bump (Breaking Change)

### Warum nicht automatisch?

- **API-Kuratierung**: Nicht alles aus Submodulen sollte public sein
- **Breaking Changes**: Automatische Entfernung wäre Breaking Change
- **Semantische Versionierung**: Bewusste Entscheidung für Version Bumps
- **Dokumentation**: Gruppierung in `__all__` bleibt erhalten

## update_versions.py

### Zweck

Aktualisiert `**Version:** X.Y.Z` in Dokumentations-Index-Dateien aus den jeweiligen
`pyproject.toml` Dateien.

### Verwendung

Wird automatisch als MkDocs Hook ausgeführt (siehe `mkdocs.yml`):

```yaml
hooks:
  - scripts/update_versions.py
```

Manuelle Ausführung:
```bash
python scripts/update_versions.py
```

### Verhalten

- Liest Versionen aus `pyproject.toml` (PEP 621 oder Poetry Format)
- Aktualisiert `docs/index.md`, `docs/data/index.md`, `docs/authentication/index.md`
- Ersetzt oder fügt `**Version:** X.Y.Z` Zeile hinzu

## Workflow: Submodule-Update

Empfohlener Workflow nach `git submodule update`:

```bash
# 1. Submodule aktualisieren
git submodule update --remote

# 2. Dokumentation synchronisieren
python scripts/sync_docs.py

# 3. Python Exports prüfen
python scripts/check_exports.py

# 4. Bei Diskrepanzen: Manuell src/questra/__init__.py anpassen
# 5. Bei neuen Exports: pyproject.toml Version bumpen
```
